ollama_agent 0.1.0 → 0.3.0

data/lib/ollama_agent/patch_risk.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  # Classifies a proposed unified diff for semi-automatic patch approval (obvious vs risky).
+  module PatchRisk
+    FORBIDDEN_PATTERNS = [
+      /\beval\s*\(/,
+      /`rm\s+-rf/,
+      /system\s*\(\s*["']sudo/,
+      /\bFile\.delete\b/,
+      /\bKernel\.exec\b/
+    ].freeze
+
+    LARGE_DIFF_LINES = 80
+
+    module_function
+
+    def large_diff_line_limit
+      v = ENV.fetch("OLLAMA_AGENT_PATCH_RISK_MAX_DIFF_LINES", nil)
+      return LARGE_DIFF_LINES if v.nil? || v.to_s.strip.empty?
+
+      Integer(v)
+    rescue ArgumentError, TypeError
+      LARGE_DIFF_LINES
+    end
+
+    def forbidden?(diff)
+      FORBIDDEN_PATTERNS.any? { |pattern| diff.match?(pattern) }
+    end
+
+    # Returns :auto_approve (no prompt) or :require_confirmation (prompt when confirm_patches is on).
+    def assess(path, diff)
+      relative = path.to_s.tr("\\", "/")
+
+      return :require_confirmation if risky?(relative, diff)
+
+      return :auto_approve if obvious_path?(relative)
+      return :auto_approve if safe_spec_change?(relative, diff)
+
+      :require_confirmation
+    end
+
+    def risky?(relative, diff)
+      forbidden?(diff) ||
+        critical_path?(relative) ||
+        large_diff?(diff) ||
+        critical_lib_file?(relative)
+    end
+
+    def large_diff?(diff, limit: nil)
+      max = limit.nil? ? large_diff_line_limit : limit
+      diff.scan(/^[-+][^-+]/).size > max
+    end
+
+    def obvious_path?(relative)
+      relative.end_with?(".md") || relative.start_with?("docs/")
+    end
+
+    def safe_spec_change?(relative, diff)
+      relative.start_with?("spec/") && !large_diff?(diff, limit: 40)
+    end
+
+    def critical_lib_file?(relative)
+      return false unless relative.start_with?("lib/")
+
+      relative.include?("sandboxed_tools") ||
+        relative.include?("patch_support") ||
+        relative.end_with?("ollama_agent/agent.rb") ||
+        relative.end_with?("ollama_agent/tools_schema.rb")
+    end
+
+    def critical_path?(relative)
+      return true if relative.match?(/\A(Gemfile|Gemfile\.lock)\z/)
+      return true if relative.end_with?(".gemspec")
+      return true if relative == "lib/ollama_agent/version.rb"
+      return true if relative.start_with?("exe/")
+
+      false
+    end
+  end
+end

data/lib/ollama_agent/patch_support.rb

@@ -8,6 +8,8 @@ module OllamaAgent
     private
 
     def patch_dry_run(diff)
+      return patch_missing_tool_message unless patch_available?
+
       output, status = Open3.capture2e(
         "patch", "-p1", "-f", "-d", @root, "--dry-run",
         stdin_data: diff
@@ -35,7 +37,8 @@ module OllamaAgent
         Re-read the file with read_file, then rebuild the diff using exact lines from that file (not placeholders).
         The @@ hunk line counts must match the hunk body the way git diff would emit them.
       MSG
-      hint.empty? ? msg : "#{msg}\n#{hint}"
+      body = hint.empty? ? msg : "#{msg}\n#{hint}"
+      body.end_with?("\n") ? body : "#{body}\n"
     end
 
     def patch_stderr_hint(detail)
@@ -65,6 +68,8 @@ module OllamaAgent
     end
 
     def apply_patch(diff)
+      return patch_missing_tool_message unless patch_available?
+
       output, status = Open3.capture2e(
         "patch", "-p1", "-f", "-d", @root,
         stdin_data: diff
@@ -74,5 +79,26 @@ module OllamaAgent
 
       patch_failure_message(output, dry_run: false)
     end
+
+    def patch_available?
+      return @patch_available if defined?(@patch_available)
+
+      @patch_available = patch_binary_usable?
+    end
+
+    def patch_binary_usable?
+      _, status = Open3.capture2e("patch", "--version")
+      return true if status.success?
+
+      _, which_status = Open3.capture2e("which", "patch")
+      which_status.success?
+    end
+
+    def patch_missing_tool_message
+      <<~MSG.strip
+        Error: ollama_agent: the `patch` program was not found or is not usable on PATH. edit_file requires GNU patch.
+        Install it (e.g. apt install patch, brew install gpatch), or on Windows use Git Bash, WSL, or GnuWin32.
+      MSG
+    end
   end
 end

data/lib/ollama_agent/path_sandbox.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module OllamaAgent
+  # Resolves paths under a project root using File.realpath so symlinks cannot escape the sandbox.
+  module PathSandbox
+    module_function
+
+    # @param root_abs [String] File.expand_path of the project root (may be a symlink path)
+    # @param root_real [String] File.realpath(root_abs) when the root exists
+    # @param user_path [String] relative or absolute path from tool args
+    def allowed?(root_abs, root_real, user_path)
+      return false if user_path.nil? || user_path.to_s.strip.empty?
+
+      expanded = Pathname(user_path.to_s).expand_path(root_abs).cleanpath.to_s
+      return false unless lexically_under_root_abs?(expanded, root_abs)
+
+      candidate_under_root?(expanded, root_real, root_abs)
+    end
+
+    def lexically_under_root_abs?(expanded_abs, root_abs)
+      expanded_abs == root_abs || expanded_abs.start_with?(root_abs + File::SEPARATOR)
+    end
+
+    def candidate_under_root?(expanded_abs, root_real, root_abs)
+      path_real = File.realpath(expanded_abs)
+      under_root_real?(path_real, root_real)
+    rescue Errno::ENOENT
+      nonexistent_path_allowed_under_root?(expanded_abs, root_real, root_abs)
+    rescue Errno::ELOOP, Errno::EACCES
+      false
+    end
+
+    def under_root_real?(path_real, root_real)
+      path_real == root_real || path_real.start_with?(root_real + File::SEPARATOR)
+    end
+
+    # rubocop:disable Metrics/MethodLength -- parent walk for missing path segments
+    def nonexistent_path_allowed_under_root?(expanded_abs, root_real, root_abs)
+      parent = expanded_abs
+      loop do
+        next_parent = File.dirname(parent)
+        break if next_parent == parent
+
+        parent = next_parent
+        begin
+          pr = File.realpath(parent)
+          return false unless under_root_real?(pr, root_real)
+
+          return lexically_under_root_abs?(expanded_abs, root_abs)
+        rescue Errno::ENOENT
+          next
+        rescue Errno::ELOOP, Errno::EACCES
+          return false
+        end
+      end
+      false
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end

data/lib/ollama_agent/prompt_skills/clean_ruby.md

@@ -0,0 +1,131 @@
+---
+name: clean-ruby-code
+description: >
+  Enforces clean Ruby code principles during all Ruby/Rails code generation, review, and refactoring tasks.
+  Applies naming conventions, method design, boolean logic, class architecture, refactoring patterns,
+  and TDD practices derived from Clean Ruby methodology. Use this skill whenever writing Ruby code,
+  reviewing Ruby pull requests, refactoring Rails models/controllers/services, creating new Ruby classes
+  or modules, writing RSpec tests, or when the user asks for code review, code improvement, naming help,
+  or architecture guidance in Ruby. Also trigger when the user mentions "clean code", "refactor",
+  "code smell", "naming", "SRP", "TDD", or "code quality" in a Ruby context. This skill should activate
+  for ANY Ruby code generation task — even if the user doesn't explicitly ask for "clean" code — because
+  all generated Ruby should be clean by default.
+---
+
+# Clean Ruby Code Agent
+
+This skill enforces clean Ruby code principles across all code generation, review, and refactoring.
+Every piece of Ruby code produced must satisfy three core qualities: **readable**, **extensible**, **simple**.
+
+## Core Philosophy
+
+Code is read far more often than it is written. Every naming choice, method signature, and class boundary
+should minimize the cognitive load on the next reader. When in doubt, choose the simpler solution —
+complexity is the enemy of maintainability.
+
+## Decision Flow
+
+When generating or reviewing Ruby code, apply these checks in order:
+
+1. **Naming** → Are all names descriptive, snake_case, verb-prefixed (methods), purpose-named (classes)?
+2. **Methods** → Fewer params? Guard clauses? Under 10 lines? No deep nesting?
+3. **Boolean Logic** → Extracted to named methods/variables? No double negatives? No raw `unless` with compound conditions?
+4. **Classes** → Simple `initialize`? SRP? Max 3 levels of inheritance? Composition where appropriate?
+5. **Refactoring** → Can any piece be simplified without losing functionality? Are there comments that should be methods?
+6. **Tests** → Does the code have clear, descriptive RSpec tests with context blocks and explicit expectations?
+
+For detailed rules on each area, read the corresponding reference file:
+
+- **Naming rules**: `references/naming.md`
+- **Method design**: `references/methods.md`
+- **Boolean logic**: `references/boolean-logic.md`
+- **Class architecture**: `references/classes.md`
+- **Refactoring patterns**: `references/refactoring.md`
+- **TDD practices**: `references/tdd.md`
+
+Read the relevant reference file(s) before generating or reviewing code in that area.
+
+## Enforcement Rules
+
+These rules apply to ALL Ruby code this agent produces or reviews:
+
+### Naming (always enforced)
+
+- Variables: snake_case, descriptive of the data, no Hungarian notation, no conjunctions ("and"/"or"), no numeric suffixes unless versioning, no crutch words (Manager, Data, Info, List)
+- Methods: verb-prefixed, `?` suffix for boolean returns, `!` suffix for destructive mutations
+- Classes: named for purpose (e.g., `UserSetup`) or role (e.g., `InActiveUserQuery`), never generic (`UserManager`)
+- Modules: named for the concept they group (e.g., `Calculable`, `Loggable`)
+
+### Methods (always enforced)
+
+- Maximum 3 parameters; use a config/params object beyond that
+- Guard clauses instead of deep `if/else` nesting
+- Target length: 5–10 lines; extract sub-operations into named private methods
+- No unnecessary intermediate variables; leverage Ruby's implicit return
+- Comments only when they explain *why*, never *what* — if a comment describes what code does, extract a method instead
+
+### Boolean Logic (always enforced)
+
+- Complex conditions → extract to a named predicate method (`def ready_to_spawn?`)
+- Never use `unless` with compound conditions (`unless a && b` is banned)
+- Avoid double negatives (`!not_found` → `found?`)
+- Use `&&` (short-circuit) not `&` (eager) unless eager evaluation is explicitly needed
+- Leverage Ruby truthy/falsy — don't write `if x == true`, write `if x`
+- Ternary only for single simple conditions; use `if/else` for compound logic
+
+### Classes (always enforced)
+
+- `initialize` does assignment only — no external calls, no side effects
+- Error-prone operations go in explicit setup methods called after instantiation
+- Limit inheritance to 3 levels; prefer composition (`has-a`) over inheritance (`is-a`)
+- Instance variables: use `attr_reader`/`attr_accessor` — avoid raw `@var` access in public methods
+- Private methods below `private` keyword, ordered by call sequence
+- If private methods are generic utilities (math, formatting), extract to a module
+
+### Refactoring (applied during review and generation)
+
+- No change is too small — rename a variable, extract a method, remove a comment
+- Replace comments with self-documenting method names
+- Apply SRP: if a class/method does two things, split it
+- Watch for shotgun surgery (one change requires edits in many places) — consolidate
+- Replace conditional chains (`if/elsif/elsif`) with polymorphism or lookup tables
+
+### TDD (applied when generating tests)
+
+- Write the test first, then the minimal implementation
+- Test descriptions: `context '#method_name'` → `it 'returns X when Y'`
+- Use `subject`, `let`, and `before` blocks — no repeated setup
+- Separate expected and actual values for clarity
+- Cover: happy path, nil inputs, edge cases, error conditions
+- Tests are production code — apply the same naming and structure rules
+
+## Anti-Patterns to Flag
+
+When reviewing code, flag these immediately:
+
+| Anti-Pattern | Fix |
+|---|---|
+| Method > 15 lines | Extract private methods |
+| > 3 params | Introduce parameter object |
+| Nested `if` > 2 levels | Guard clauses or extract predicate |
+| `unless` with `&&`/`||` | Convert to `if` with inverted logic |
+| Comment describing *what* | Extract named method |
+| God class (> 200 lines) | Split by responsibility |
+| `initialize` with side effects | Move to explicit setup method |
+| Generic name (Manager, Helper, Data) | Rename to purpose/role |
+| Double negative (`!not_x`) | Invert the method name |
+| Bare `rescue` | Rescue specific exceptions |
+
+## Output Format
+
+When generating Ruby code, structure output as:
+
+1. The code itself — complete, runnable, following all rules above
+2. If refactoring existing code: brief annotation of what changed and why (1-2 lines per change)
+3. If the user asked for review: list violations as `[RULE] description → fix` format
+
+When the code is part of a Rails app, also apply:
+- Models: thin, no business logic beyond validations and scopes
+- Controllers: thin, delegate to domain objects
+- Services: only for orchestration across multiple domain objects or external systems
+- Queries: extract complex `where` chains to query objects (e.g., `InActiveUserQuery`)

data/lib/ollama_agent/prompt_skills/code_review.md

@@ -0,0 +1,112 @@
+---
+name: code-review
+description: Structured code review for Ruby/Rails projects. Detects file type, scans the local codebase for project-specific patterns first, then applies global skills in priority order. Use when asked to review, audit, or check code quality.
+disable-model-invocation: true
+argument-hint: [file-or-directory]
+allowed-tools: Read, Glob, Grep
+---
+
+# Code Review — Orchestrator
+
+Perform a structured code review of `$ARGUMENTS`. Follow this exact workflow.
+
+## Step 1 — Identify File Type
+
+| File Pattern | Type | Primary Skills |
+|---|---|---|
+| `app/controllers/**` | Controller | rails-best-practices, solid-ruby |
+| `app/models/**` | Model | rails-best-practices, solid-ruby, ruby-design-patterns |
+| `app/services/**` | Service Object | solid-ruby, rails-best-practices |
+| `app/workers/**`, `app/jobs/**` | Background Job | rails-best-practices, solid-ruby |
+| `spec/**/*_spec.rb` | RSpec spec | rspec, solid-ruby |
+| `db/migrate/**` | Migration | rails-best-practices |
+| `config/routes.rb` | Routes | rails-best-practices |
+| `app/views/**` | View/Partial | rails-best-practices, ruby-style |
+| `lib/**` | Library | solid-ruby, ruby-style, ruby-design-patterns |
+
+## Step 2 — Scan Project for Existing Patterns (MANDATORY)
+
+Before applying any rule, read 2–3 similar files in the same directory to extract project conventions.
+
+**Find and extract:**
+- Controllers: response format, base controller, auth pattern, error format, param naming
+- Models: shared concerns/modules, validation style, enum convention, scope naming
+- Services: calling convention (`.call` vs `.run`), return type, class naming, base class
+- Specs: factory style, shared examples, helper includes, context naming
+
+See [project-pattern-detection.md](project-pattern-detection.md) for full detection checklist.
+
+## Step 3 — Review in Priority Order
+
+### 🔴 CRITICAL — Always flag, regardless of project style
+- SQL injection via string interpolation
+- Missing Strong Parameters / mass assignment vulnerability
+- `rescue Exception` (swallows signals)
+- User input in file paths, shell commands, or redirects
+- Hardcoded credentials or secrets
+- `save` return value silently ignored
+- Auth check missing or bypassable
+- Sensitive data logged
+
+### 🟠 PERFORMANCE — Always flag
+- N+1 queries (association in loop without preload)
+- `.where` / query methods in AR instance methods (breaks preloading)
+- `.count` where `.size` should be used
+- `any?`/`empty?` then `.each` on same relation (two queries)
+- `exists?` called multiple times (never memoized)
+- `find_each` missing on large dataset iteration
+- No timeout on external HTTP/Redis calls
+- `after_save` for side effects instead of `after_commit`
+
+### 🟡 PROJECT CONSISTENCY — Most important correctness layer
+Compare against patterns found in Step 2. Phrase as: "The rest of the codebase does X — this does Y."
+- Different service calling convention
+- Different response/error format in controller
+- Different factory/spec helper pattern
+- Missing shared concern/module that all similar models include
+- Different enum/scope/validation naming
+
+### 🔵 BEST PRACTICES — Apply where no project pattern covers
+Reference: rails-best-practices, solid-ruby, rspec, ruby-design-patterns
+
+### ⚪ STYLE — Only if clearly inconsistent
+Reference: ruby-style, rails-style
+
+## Step 4 — Output Format
+
+```
+## Code Review: [filename]
+**Type:** [file type]
+**Project patterns detected:** [1-line summary]
+
+### 🔴 CRITICAL | [title]
+**File:** path/to/file.rb:42
+**Issue:** [what and why]
+**Fix:**
+# Before / After code
+**Rule:** [source]
+
+[repeat per finding, skip empty severity sections]
+
+---
+## Verdict: SHIP ✅ | NEEDS FIXES 🔧 | CRITICAL ISSUES 🚨
+
+- 🔴 Critical: N
+- 🟠 Performance: N
+- 🟡 Consistency: N
+- 🔵 Best Practice: N
+- ⚪ Style: N
+
+Must fix before merge: [list]
+Can fix in follow-up: [list]
+```
+
+After verdict, ask: "Want me to apply the fixes?"
+
+## Behavior Rules
+- Cannot find similar files → say so, proceed with global skills only
+- Do not flag style as critical
+- Do not invent violations — only flag what is visible in the code
+- Project patterns beat global skills when they conflict
+- One finding per issue — no duplicates across severity levels
+- For specs: also check that the spec tests what production code actually does

data/lib/ollama_agent/prompt_skills/design_patterns.md

@@ -0,0 +1,56 @@
+---
+name: ruby-design-patterns
+description: All 23 GoF design patterns with Ruby implementations from refactoring.guru. Use when designing or refactoring Ruby/Rails code and you need to apply or recognize a design pattern. Covers Creational (5), Structural (7), and Behavioral (11) patterns with Ruby code examples and Rails-specific applications.
+disable-model-invocation: true
+---
+
+# Ruby Design Patterns — Complete Reference
+
+Source: https://refactoring.guru/design-patterns/ruby
+
+> Don't force patterns. Let them emerge from refactoring. Apply when you recognize the problem, not speculatively.
+
+## By Problem — Quick Lookup
+
+| Problem | Pattern | Category |
+|---|---|---|
+| Creating families of compatible objects | Abstract Factory | Creational |
+| Building complex objects step by step | Builder | Creational |
+| Subclass decides which object to create | Factory Method | Creational |
+| Clone objects without coupling to class | Prototype | Creational |
+| One instance globally | Singleton | Creational |
+| Incompatible interfaces must work together | Adapter | Structural |
+| Split abstraction from implementation | Bridge | Structural |
+| Tree structures, treat parts and wholes uniformly | Composite | Structural |
+| Add behavior without subclassing | Decorator | Structural |
+| Simplify a complex subsystem | Facade | Structural |
+| Share common state across many objects | Flyweight | Structural |
+| Control access to an object | Proxy | Structural |
+| Pass request through a handler chain | Chain of Responsibility | Behavioral |
+| Encapsulate a request as an object | Command | Behavioral |
+| Traverse a collection without exposing it | Iterator | Behavioral |
+| Decouple communicating objects | Mediator | Behavioral |
+| Save and restore object state | Memento | Behavioral |
+| Notify many objects about events | Observer | Behavioral |
+| Alter behavior when state changes | State | Behavioral |
+| Swap algorithms at runtime | Strategy | Behavioral |
+| Define algorithm skeleton, defer steps | Template Method | Behavioral |
+| Add operations without modifying classes | Visitor | Behavioral |
+
+## Ruby-Native Pattern Support
+
+| Pattern | Ruby built-in |
+|---|---|
+| Iterator | `Enumerable`, `Enumerator` |
+| Observer | `Observable` module (stdlib) |
+| Singleton | `Singleton` module (stdlib) |
+| Decorator | Modules + `prepend` / `extend` |
+| Strategy | Blocks / Procs / lambdas |
+| Template Method | Inheritance + hook methods |
+| Command | Proc / Method objects |
+
+## Pattern Detail Files
+
+- [Creational Patterns (1–5)](creational-patterns.md) — Abstract Factory, Builder, Factory Method, Prototype, Singleton
+- [Structural Patterns (6–12)](structural-patterns.md) — Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy
+- [Behavioral Patterns (13–22)](behavioral-patterns.md) — Chain of Responsibility, Command, Iterator, Mediator, Memento, Observer, State, Strategy, Template Method, Visitor

data/lib/ollama_agent/prompt_skills/manifest.yml

@@ -0,0 +1,25 @@
+# Ordered bundled prompt skills (ids used by OLLAMA_AGENT_SKILLS_INCLUDE / EXCLUDE).
+version: 1
+skills:
+  - id: clean_ruby
+    file: clean_ruby.md
+  - id: ruby_style
+    file: ruby_style.md
+  - id: rubocop
+    file: rubocop.md
+  - id: solid
+    file: solid.md
+  - id: solid_ruby
+    file: solid_ruby.md
+  - id: design_patterns
+    file: design_patterns.md
+  - id: rspec
+    file: rspec.md
+  - id: rails_style
+    file: rails_style.md
+  - id: rails_best_practices
+    file: rails_best_practices.md
+  - id: code_review
+    file: code_review.md
+  - id: ollama_agent_patterns
+    file: ollama_agent_patterns.md

data/lib/ollama_agent/prompt_skills/ollama_agent_patterns.md

@@ -0,0 +1,132 @@
+---
+name: ollama-agent-patterns
+description: >-
+  Blueprint for building a CLI Ollama-based coding agent (Ruby gem) with design
+  patterns and judicious metaprogramming—Facade, Template Method, Factory/Registry,
+  Builder, Adapter, Proxy, Command, Observer, Strategy, State, and tool DSLs. Use
+  when working on ollama_agent, ollama-client integration, tools, LLM adapters,
+  prompts, streaming, patch application, or when the user asks for agent
+  architecture, extensibility, registries, or Ruby metaprogramming for agents.
+---
+
+# Skill: Ollama Agent — Design Patterns & Metaprogramming
+
+## 1. Overview
+
+Blueprint for a **CLI coding agent** (e.g. `ollama_agent`) that uses **ollama-client** to chat with tools: read/search files, apply small unified diffs from natural language. Patterns keep the design **extensible and maintainable** without front-loading complexity.
+
+## 2. Core components & patterns
+
+| Component | Pattern(s) | Purpose |
+|-----------|------------|---------|
+| **Agent** | Facade, Template Method | Simple API (`run`); skeleton loop with overridable steps. |
+| **Tools** | Factory Method, Command, Registry | Load/execute tools; optional logging/replay/undo. |
+| **LLM client** | Adapter, (optional) Proxy | Swap backends; logging/metrics without forking core. |
+| **Prompts** | Builder | Fluent construction of messages + tools + options. |
+| **Streaming** | Observer | Multiple subscribers for tokens (UI, logs). |
+| **Patch application** | Strategy | Swap `patch(1)` vs Ruby-native apply, etc. |
+| **Conversation** | State | Phases (idle, tools, confirmation) without giant `if/else`. |
+
+**Client lifetime:** **Singleton** is optional. Prefer **injectable** `Ollama::Client` (or adapter) for tests and per-run config (`timeout`, `base_url`, `api_key`).
+
+## 3. Principles
+
+1. **Start simple** — add Factory, State, Strategy when duplication or branching hurts; do not adopt every pattern up front.
+2. **Core loop stays explicit** — readable `run` / tool loop; collaborators (`Adapter`, `PromptBuilder`, `ToolCommand`) hide detail, not `send` spaghetti.
+3. **Metaprogramming at boundaries** — registration / DSLs at tool edges; avoid dynamic dispatch in error paths and hot loops unless measured.
+4. **Workspace rules** — validated tool schemas; loggable/replayable actions; **no hardcoded model names** (runtime config).
+
+## 4. Pattern map (where code lives)
+
+| Area | Patterns | Role |
+|------|-----------|------|
+| **Agent** | Facade, Template Method | Single entry; fixed loop with overridable hooks. |
+| **Tools** | Factory, Command, Registry | Instantiate tools; optional command objects for audit. |
+| **LLM** | Adapter, Proxy | Backends; cross-cutting logging/rate limits. |
+| **Prompts** | Builder | Messages + tools + options. |
+| **Streaming** | Observer | Fan-out from client `hooks`. |
+| **Patches** | Strategy | Pluggable apply path. |
+| **Conversation** | State | Explicit phases when control flow grows. |
+
+### Target layout (illustrative)
+
+A fuller **pattern-oriented** tree (with `bin/console`, `commands/`, `strategies/`, `states/`, etc.) and a **“this repo today”** note live in **reference.md** under *Recommended gem structure*. Migrate only when complexity justifies new directories.
+
+```
+ollama_agent/
+├── exe/ollama_agent
+├── lib/ollama_agent.rb
+└── lib/ollama_agent/
+    ├── agent.rb
+    ├── cli.rb
+    ├── prompt_builder.rb      # Builder (optional)
+    ├── tool_registry.rb
+    ├── tools/base.rb
+    ├── tools/
+    ├── llm/base_adapter.rb
+    ├── llm/ollama_adapter.rb
+    ├── llm/logging_proxy.rb
+    ├── commands/tool_command.rb
+    ├── observers/
+    ├── strategies/
+    └── states/
+```
+
+## 5. Creational patterns (summary)
+
+- **Factory + registry** — Replace a growing `case` with `ToolRegistry.get(name)`; auto-register via `inherited` **or** explicit `tool_name` + hash (clearer than magic naming).
+- **Builder** — `PromptBuilder` when message construction branches; skip until you have real optional composition.
+- **Singleton** — Avoid as default for HTTP clients; use when you truly need one process-wide resource and tests can still stub.
+
+## 6. Structural patterns (summary)
+
+- **Adapter** — Common `chat(messages:, tools:, **options)` surface for Ollama vs future providers.
+- **Proxy** — Wrap adapter for logging/metrics; keep thin.
+- **Facade** — `Agent#run` — already the right shape.
+
+## 7. Behavioral patterns (summary)
+
+- **Command** — Wrap tool invocations when you need queues, structured logs, or replay; **undo** only with a real story (VCS/snapshots).
+- **Observer** — Fan-out streaming tokens; compose with ollama-client `hooks`.
+- **Strategy** — `PatchStrategy` if you need non-`patch` apply paths.
+- **State** — When confirmation + tool rounds + idle become tangled.
+- **Template Method** — Base agent class only if you have **multiple** agent variants sharing one loop.
+
+## 8. Metaprogramming (judicious)
+
+| Technique | Use when | Caution |
+|-----------|----------|--------|
+| **`inherited` + registry** | Many tools, stable naming | Keep in sync with **tool JSON schema**; consider explicit `tool_name`. |
+| **Tool DSL** (`tool :name do …`) | Repetition dominates | Stack traces and IDE nav suffer; keep DSL thin. |
+| **`send` for hooks** | Fixed event names | Prefer explicit methods for public API. |
+| **`method_missing`** | Rare delegation | Not for core tool dispatch — use a Hash/registry. |
+| **Plugin `extend`** | Third-party tools | Document load order and sandbox rules. |
+
+## 9. When to avoid heavy metaprogramming
+
+- Main agent loop and **error handling** — explicit flow wins.
+- **Performance-sensitive** inner loops — measure before dynamic dispatch.
+- **Public APIs** — stable, documented entry points over hidden DSL magic.
+
+## 10. Summary
+
+| Pattern | Benefit |
+|---------|---------|
+| Factory Method | Decouples tool creation from call sites. |
+| Builder | Composes prompts/options without positional arg soup. |
+| Singleton | Single shared resource (use sparingly for HTTP clients). |
+| Adapter | Multiple LLM backends behind one shape. |
+| Proxy | Cross-cutting concerns on the client. |
+| Facade | Hides orchestration from CLI users. |
+| Command | Tool calls as objects (log/replay/queue). |
+| Observer | Decoupled streaming consumers. |
+| Strategy | Swappable patch application. |
+| State | Explicit conversation phases. |
+| Template Method | Shared loop, varied steps. |
+| Metaprogramming | Less boilerplate at **boundaries** only. |
+
+**Start with straightforward code; refactor into patterns when pain appears.**
+
+## 11. Full code examples
+
+Runnable snippets (registry, `PromptBuilder`, adapters, proxy, command, observer, strategy, state, template-method skeleton, DSL sketch) live in **[reference.md](reference.md)**. Prefer copying from there and adapting to the real `ollama-client` API and this repo’s `SandboxedTools` / `tools_schema` constraints.