ralph.rb 1.2.435535439

data/ralph.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/ralph/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ralph.rb"
+  spec.version = Ralph::VERSION
+  spec.authors = ["Nathan Kidd"]
+  spec.email = ["nathankidd@hey.com"]
+
+  spec.summary = "Autonomous agentic loop for Claude Code, Codex & OpenCode"
+
+  spec.description = <<~DESC
+    Ralph Wiggum Loop - Iterative AI development with AI agents.
+    An autonomous agentic loop that drives Claude Code, Codex, and OpenCode.
+  DESC
+
+  spec.homepage = "https://github.com/n-at-han-k/ralph.rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+end

data/ralph2.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/ralph/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ralph"
+  spec.version = Ralph::VERSION
+  spec.authors = ["Nathan Kidd"]
+  spec.email = ["nathankidd@hey.com"]
+
+  spec.summary = "Autonomous agentic loop for Claude Code, Codex & OpenCode"
+
+  spec.description = <<~DESC
+    Ralph Wiggum Loop - Iterative AI development with AI agents.
+    An autonomous agentic loop that drives Claude Code, Codex, and OpenCode.
+  DESC
+
+  spec.homepage = "https://github.com/n-at-han-k/ralph.rb"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = spec.homepage
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+end

data/specs/README.md

@@ -0,0 +1,46 @@
+<!--
+ Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.
+ SPDX-License-Identifier: Proprietary
+-->
+
+<!--
+  HOW TO MAINTAIN THIS FILE
+
+  This is the index of all design specifications for Ralph.rb.
+  Each row links a spec document to its implementation code and a short purpose summary.
+
+  When adding a new spec:
+  1. Create the markdown file in this directory (specs/)
+  2. Add a row to the appropriate table section below
+  3. Link the spec file, the code path it describes, and a brief purpose
+
+  Table format:
+    | [spec-name.md](./spec-name.md) | [path/to/code](../path/to/code) | Short description |
+
+  Use "—" in the Code column if the spec has no implementation yet.
+  Group specs under heading sections by domain area.
+-->
+
+# Ralph.rb Specifications
+
+Design documentation for Ralph.rb, a Ruby CLI that runs iterative AI development loops.
+
+## Core
+
+| Spec | Code | Purpose |
+|------|------|---------|
+| [agents.md](./agents.md) | [lib/ralph/agents/](../lib/ralph/agents/) | Agent abstraction: base class, subclasses, CLI resolution, subprocess argument building |
+| [cli.md](./cli.md) | [lib/ralph/cli.rb](../lib/ralph/cli.rb) | CLI options, subcommands, prompt resolution, error handling |
+## Data Storage
+
+| Spec | Code | Purpose |
+|------|------|---------|
+| [storage/local-data-structure.md](./storage/local-data-structure.md) | [lib/ralph/storage/](../lib/ralph/storage/) | Ralph state persistence: .ralph/ directory, storage module architecture, data lifecycle |
+| [tasks.md](./tasks.md) | [lib/ralph/storage/tasks.rb](../lib/ralph/storage/tasks.rb) | Task management: file format, data models, storage, lifecycle in the loop, prompt integration |
+
+## Output
+
+| Spec | Code | Purpose |
+|------|------|---------|
+| [output.md](./output.md) | [lib/ralph/output/](../lib/ralph/output/) | Terminal output structure: callable object pattern, channels, formatting conventions |
+

data/specs/agents.md

@@ -0,0 +1,172 @@
+# Agents Specification
+
+The `Ralph::Agents` module provides a polymorphic abstraction over the external AI coding CLIs that Ralph can invoke. Each supported agent is a subclass of `Ralph::Agents::Base`, encapsulating its CLI invocation details, output parsing, and validation.
+
+## Namespace & File Layout
+
+```
+lib/ralph/agents/
+  base.rb          # Ralph::Agents::Base (abstract), module-level resolve/valid_agent_names
+  open_code.rb     # Ralph::Agents::OpenCode
+  claude_code.rb   # Ralph::Agents::ClaudeCode
+  codex.rb         # Ralph::Agents::Codex
+```
+
+Each file defines exactly one class inside `module Ralph; module Agents; ... end; end`, except `base.rb` which also defines the module-level lookup functions and the `AGENT_NAME_MAP` constant.
+
+## Module Interface
+
+The `Ralph::Agents` module exposes two module-level functions for agent discovery and resolution.
+
+### `Agents.resolve(name_str) -> Base | nil`
+
+Maps a CLI name string to a new agent instance.
+
+- **Parameter:** `name_str` — String, one of the keys in `AGENT_NAME_MAP`
+- **Returns:** A new instance of the matching agent subclass, or `nil` if the name is unknown
+- **Consumers:** `Loop#resolve_agent!`, `Output::Status`
+
+### `Agents.valid_agent_names -> Array<String>`
+
+Returns the list of accepted CLI agent name strings for option parsing.
+
+- **Returns:** `["opencode", "claude-code", "codex"]`
+- **Consumer:** `CLI` (used in OptionParser `--agent` validation and help text)
+
+### `AGENT_NAME_MAP`
+
+Frozen hash mapping CLI strings to internal symbols used for subclass dispatch.
+
+```ruby
+AGENT_NAME_MAP = {
+  "opencode"   => :opencode,
+  "claude-code" => :claude_code,
+  "codex"      => :codex
+}.freeze
+```
+
+## Base Class
+
+`Ralph::Agents::Base` is an abstract class that includes `Ralph::Helpers` and defines the interface every agent subclass must implement.
+
+### Abstract Methods
+
+Subclasses must override all of the following. The base implementations raise `NotImplementedError`.
+
+| Method | Signature | Returns | Purpose |
+|--------|-----------|---------|---------|
+| `type` | `-> Symbol` | `:opencode`, `:claude_code`, or `:codex` | Internal identifier used for agent-specific branching |
+| `command` | `-> String` | CLI binary name | The executable name looked up on `$PATH` |
+| `config_name` | `-> String` | Human-readable name | Display name used in banners, warnings, status output |
+| `build_args` | `(prompt, model, options) -> Array<String>` | CLI argument array | Constructs the argument list for the agent subprocess |
+| `parse_tool_output` | `(line) -> String or nil` | Tool name or nil | Extracts a tool invocation name from a single output line |
+
+### Concrete Methods
+
+| Method | Signature | Returns | Purpose |
+|--------|-----------|---------|---------|
+| `build_env` | `(options) -> Hash<String, String>` | Environment hash | Returns `ENV.to_h.dup`. Subclasses may override to customise the subprocess environment |
+| `validate!` | `-> void` | — | Checks that `command` is found on `$PATH` via `which`. Prints an error to `$stderr` and calls `exit 1` if missing |
+
+### `build_args` Parameters
+
+- `prompt` — String, the full prompt text to send to the agent
+- `model` — String, model identifier (may be `nil` or empty to use the agent's default)
+- `options` — Hash with execution options:
+  - `:allow_all_permissions` — Boolean, whether to pass auto-approve flags
+
+### `parse_tool_output` Behaviour
+
+- Strips ANSI escape sequences from the line via `strip_ansi` (from `Ralph::Helpers`)
+- Applies an agent-specific regex to extract a tool name
+- Returns the tool name `String` if matched, `nil` otherwise
+- **Consumers:** `Iteration#stream_agent` (real-time tool counting), `Helpers.collect_tool_summary_from_text` (post-hoc counting)
+
+## Agent Subclasses
+
+### `Ralph::Agents::OpenCode`
+
+| Property | Value |
+|----------|-------|
+| `type` | `:opencode` |
+| `command` | `"opencode"` |
+| `config_name` | `"OpenCode"` |
+
+**`build_args` behaviour:**
+1. Starts with `["run"]`
+2. Appends `["-m", model]` if model is non-empty
+3. Appends the prompt as the final argument
+
+**`parse_tool_output` regex:** `/^\|\s{2}([A-Za-z0-9_-]+)/`
+
+Matches OpenCode's tool output format where tool names appear after a pipe and two spaces at the start of a line.
+
+### `Ralph::Agents::ClaudeCode`
+
+| Property | Value |
+|----------|-------|
+| `type` | `:claude_code` |
+| `command` | `"claude"` |
+| `config_name` | `"Claude Code"` |
+
+**`build_args` behaviour:**
+1. Starts with `["-p", prompt]`
+2. Appends `["--model", model]` if model is non-empty
+3. Appends `"--dangerously-skip-permissions"` if `options[:allow_all_permissions]` is truthy
+
+**`parse_tool_output` regex:** `/(?:Using|Called|Tool:)\s+([A-Za-z0-9_-]+)/i`
+
+Matches Claude Code's tool output format where tool names follow "Using", "Called", or "Tool:" prefixes (case-insensitive).
+
+### `Ralph::Agents::Codex`
+
+| Property | Value |
+|----------|-------|
+| `type` | `:codex` |
+| `command` | `"codex"` |
+| `config_name` | `"Codex"` |
+
+**`build_args` behaviour:**
+1. Starts with `["exec"]`
+2. Appends `["--model", model]` if model is non-empty
+3. Appends `"--full-auto"` if `options[:allow_all_permissions]` is truthy
+4. Appends the prompt as the final argument
+
+**`parse_tool_output` regex:** `/(?:Tool:|Using|Calling|Running)\s+([A-Za-z0-9_-]+)/i`
+
+Matches Codex's tool output format where tool names follow "Tool:", "Using", "Calling", or "Running" prefixes (case-insensitive).
+
+## Consumers
+
+| Consumer | What it uses | How |
+|----------|-------------|-----|
+| `Loop#resolve_agent!` | `Agents.resolve`, `agent.validate!` | Resolves CLI name to instance, validates binary exists |
+| `Loop#initialize` | `agent.type`, `agent.config_name` | Agent-specific branching (plugin warnings), display name for banner/warnings |
+| `Iteration#execute_agent` | `agent.build_args`, `agent.build_env`, `agent.command` | Constructs and spawns the agent subprocess |
+| `Iteration#stream_agent` | `agent.parse_tool_output` | Real-time tool counting during streaming output |
+| `Helpers.collect_tool_summary_from_text` | `agent.parse_tool_output` | Post-hoc tool counting from buffered output |
+| `Output::Status` | `Agents.resolve`, `agent.config_name` | Display name in `--status` dashboard |
+| `CLI` | `Agents.valid_agent_names` | OptionParser validation and help text for `--agent` flag |
+
+## Adding a New Agent
+
+To add support for a new AI coding CLI:
+
+1. Create `lib/ralph/agents/<name>.rb` with a class inheriting from `Base`
+2. Implement all abstract methods: `type`, `command`, `config_name`, `build_args`, `parse_tool_output`
+3. Override `build_env` if the agent requires custom environment variables
+4. Add an entry to `AGENT_NAME_MAP` in `base.rb`
+5. Add a constructor lambda to the dispatch hash in `Agents.resolve`
+
+## Testing Strategy
+
+### Unit Tests
+- Verify each subclass returns correct `type`, `command`, and `config_name`
+- Test `build_args` with combinations of: empty model, non-empty model, permissions on/off
+- Test `parse_tool_output` with matching lines, non-matching lines, and lines containing ANSI escapes
+- Test `Agents.resolve` returns correct class for each valid name, `nil` for unknown names
+- Test `Agents.valid_agent_names` returns expected list
+
+### Integration Tests
+- Test `validate!` with a mocked `which` that returns nil (expect stderr output and `SystemExit`)
+- Test `validate!` with a mocked `which` that returns a path (expect no error)

data/specs/cli.md

@@ -0,0 +1,223 @@
+# CLI Specification
+
+Ralph is invoked as a single binary with positional arguments, flags, and subcommands.
+
+```
+ralph "<prompt>" [options]
+ralph <subcommand> [args]
+```
+
+## Prompt Input
+
+The primary argument is a prompt string describing the task for the AI agent.
+
+| Input method | Syntax | Notes |
+|---|---|---|
+| Inline string | `ralph "Build a REST API"` | One or more positional args joined with spaces |
+| Piped input | `cat prompt.md \| ralph` | Read prompt from stdin via shell pipe |
+| Command substitution | `ralph $(cat prompt.md)` | Expand file contents as arguments |
+
+### Prompt resolution order
+
+1. Join all positional args with spaces.
+2. If the resolved prompt is empty, exit with an error.
+
+## Loop Options
+
+These flags configure the main iteration loop.
+
+### `--agent AGENT`
+
+Select the AI agent to use.
+
+- **Type:** String, restricted to valid agent names
+- **Valid values:** `opencode`, `claude-code`, `codex`
+- **Default:** `opencode`
+- **Error on invalid value:** Yes (OptionParser rejects with `invalid argument`)
+
+### `--min-iterations N`
+
+Minimum number of iterations before a completion promise is accepted.
+
+- **Type:** Integer
+- **Default:** `1`
+- **Behavior:** If the agent outputs the completion promise before this many iterations have run, the loop continues anyway.
+
+### `--max-iterations N`
+
+Maximum number of iterations before the loop stops automatically.
+
+- **Type:** Integer
+- **Default:** `0` (unlimited)
+- **Behavior:** When the iteration counter exceeds this value, the loop stops and clears state.
+
+### Validation
+
+`--min-iterations` must not exceed `--max-iterations` (when max > 0). The CLI exits with an error if this constraint is violated.
+
+### `--completion-promise TEXT`
+
+The phrase the agent must output (wrapped in `<promise>...</promise>` tags) to signal task completion.
+
+- **Type:** String
+- **Default:** `COMPLETE`
+
+### `--tasks`, `-t`
+
+Enable Tasks Mode for structured task tracking.
+
+- **Type:** Boolean flag
+- **Default:** `false`
+- **Behavior:** When enabled, the loop works through tasks defined in `.ralph/ralph-tasks.md` one at a time. The prompt builder includes task-specific instructions and workflow guidance.
+
+### `--task-promise TEXT`
+
+The phrase the agent outputs to signal an individual task is complete (tasks mode only).
+
+- **Type:** String
+- **Default:** `READY_FOR_NEXT_TASK`
+
+### `--model MODEL`
+
+Model identifier passed to the selected agent.
+
+- **Type:** String
+- **Default:** `""` (agent's default)
+- **Agent-specific:** The value is passed directly to the agent CLI (e.g., `--model` for claude-code/codex, `-m` for opencode).
+
+### `--[no-]stream`
+
+Control whether agent output is streamed in real-time or buffered.
+
+- **Type:** Boolean
+- **Default:** `true` (streaming on)
+- **`--stream`:** Stream stdout/stderr in real-time with tool counting and heartbeat.
+- **`--no-stream`:** Buffer all output, print at end. Tool counts collected post-hoc.
+
+### `--verbose-tools`
+
+Print every tool invocation line instead of periodic compact summaries.
+
+- **Type:** Boolean flag
+- **Default:** `false`
+- **Behavior:** When off (default), tool lines are suppressed and a compact summary is printed every 3 seconds. When on, every tool line is printed as-is.
+
+### `--no-plugins`
+
+Disable non-auth OpenCode plugins for the current run.
+
+- **Type:** Boolean flag
+- **Default:** `false`
+- **Agent-specific:** Only affects `opencode`. Prints a warning if used with `claude-code` or `codex`.
+- **Behavior:** Generates a filtered OpenCode config that only includes plugins matching `/auth/i`.
+
+### `--[no-]commit`
+
+Control automatic git commits after each iteration.
+
+- **Type:** Boolean
+- **Default:** `true` (auto-commit on)
+- **`--commit`:** After each iteration, if `git status --porcelain` shows changes, run `git add -A && git commit -m "Ralph iteration N: work in progress"`.
+- **`--no-commit`:** Skip auto-commits.
+
+### `--[no-]allow-all`
+
+Control automatic tool permission approval.
+
+- **Type:** Boolean
+- **Default:** `true` (auto-approve on)
+- **`--allow-all`:** Pass permission flags to the agent (`--dangerously-skip-permissions` for claude-code, `--full-auto` for codex, permission config for opencode).
+- **`--no-allow-all`:** Require interactive permission prompts from the agent.
+
+## Subcommands
+
+Subcommands are flag-style (prefixed with `--`) and cause the CLI to perform a specific action then exit. They do not start the main loop.
+
+### `--version`, `-v`
+
+Print `ralph <VERSION>` and exit 0.
+
+### `--help`, `-h`
+
+Print the full help text (generated by OptionParser) and exit 0.
+
+### `--status`
+
+Display the current loop status, pending context, and iteration history, then exit 0.
+
+- **With `-t` or `--tasks`:** Also display the current task list from `.ralph/ralph-tasks.md`.
+- **When an active loop has `tasks_mode` enabled:** Task list is shown automatically.
+- **Output includes:**
+  - Active/inactive status
+  - Current iteration, start time, elapsed time
+  - Completion promise, agent, model
+  - Pending context (if any)
+  - Task list with progress (if shown)
+  - Last 5 iterations with duration and top tools
+  - Struggle indicators (if detected)
+
+### `--add-context TEXT`
+
+Append context text to `.ralph/ralph-context.md` for the next iteration.
+
+- **Requires:** A text argument (exits with error if missing)
+- **Behavior:** Appends a timestamped section. Creates the file if it doesn't exist. The context is injected into the prompt on the next iteration, then cleared.
+
+### `--clear-context`
+
+Delete `.ralph/ralph-context.md` if it exists.
+
+### `--list-tasks`
+
+Parse and display tasks from `.ralph/ralph-tasks.md` with numbered indices and status icons.
+
+- Exits with a message if no tasks file exists.
+
+### `--add-task DESC`
+
+Append a new `- [ ] DESC` line to `.ralph/ralph-tasks.md`.
+
+- **Requires:** A description argument.
+- Creates the file with a header if it doesn't exist.
+
+### `--remove-task N`
+
+Remove task at 1-based index N (including its subtasks) from `.ralph/ralph-tasks.md`.
+
+- **Requires:** An integer argument.
+- **Validation:** Index must be in range `1..task_count`.
+- **Behavior:** Removes the top-level task line and any indented lines immediately following it (subtasks/notes).
+
+## Error Handling
+
+| Condition | Behavior |
+|---|---|
+| Unknown option | Exit 1, print message + `Run 'ralph --help'` |
+| Invalid option value (bad agent, non-integer) | Exit 1, OptionParser error message + `Run 'ralph --help'` |
+| No prompt provided | Exit 1, print usage hint |
+| min-iterations > max-iterations | Exit 1, print constraint error |
+| Agent CLI not found in PATH | Exit 1, print which agent is missing |
+| Loop already active | Exit 1, print active loop info and state file path |
+| Fatal error during loop | Exit 1, clear state, print error |
+
+## Options Hash
+
+After parsing, the CLI produces an options hash passed to `Ralph::Loop.run`:
+
+```ruby
+{
+  prompt: String,              # resolved prompt text
+  min_iterations: Integer,     # >= 1
+  max_iterations: Integer,     # 0 = unlimited
+  completion_promise: String,  # default "COMPLETE"
+  tasks_mode: Boolean,         # default false
+  task_promise: String,        # default "READY_FOR_NEXT_TASK"
+  model: String,               # default ""
+  chosen_agent: String,          # default "opencode"
+  auto_commit: Boolean,        # default true
+  disable_plugins: Boolean,    # default false
+  allow_all_permissions: Boolean, # default true
+  stream_output: Boolean,      # default true
+  verbose_tools: Boolean,      # default false
+}
+```

data/specs/iteration.md

@@ -0,0 +1,173 @@
+# Iteration Class Specification
+
+## Purpose
+
+The `Iteration` class is responsible for executing a single AI agent iteration and collecting metrics. It handles the low-level execution details while delegating business logic decisions to the caller.
+
+## Location
+
+`lib/ralph/iteration.rb`
+
+## Dependencies
+
+```ruby
+require_relative "types"
+require_relative "helpers"
+require_relative "state"
+```
+
+## Class Interface
+
+### Constructor
+
+```ruby
+def initialize(loop)
+```
+
+**Parameters:**
+- `loop` - `Ralph::Loop` instance. Provides access to:
+  - `loop.config` - `Ralph::Config` instance with all execution options (model, stream_output, verbose_tools, allow_all_permissions, disable_plugins, completion_promise, etc.)
+  - `loop.agent_config` - `Ralph::Agents::Base` instance providing command, build_args, build_env, etc. (see [agents.md](./agents.md))
+
+### Main Method
+
+```ruby
+def call(prompt, iteration_start:)
+```
+
+**Parameters:**
+- `prompt` - String containing the prompt to send to the agent
+- `iteration_start` - Integer timestamp (ms) when the iteration started
+
+**Returns:**
+- `IterationResult` struct with execution data
+
+## Result Type
+
+```ruby
+IterationResult = Struct.new(
+  :duration_ms,        # Integer - execution duration in milliseconds
+  :exit_code,          # Integer - agent process exit code
+  :stdout_text,        # String - agent stdout output
+  :stderr_text,        # String - agent stderr output
+  :tool_counts,        # Hash<String, Integer> - tool usage counts
+  :files_modified,     # Array<String> - list of files changed during iteration
+  :completion_detected, # Boolean - whether completion promise was found
+  :errors,             # Array<String> - extracted errors from output
+  :success             # Boolean - overall success (no crashes, exit_code == 0)
+)
+```
+
+## Internal Responsibilities
+
+### 1. Agent Execution
+- Build agent command using `agent_config.build_args` and `agent_config.build_env`
+- Execute agent (streaming or buffered based on options)
+- Capture stdout, stderr, exit code, and tool usage data
+- Handle agent process lifecycle
+
+### 2. Metrics Collection
+- Calculate execution duration from `iteration_start`
+- Extract tool counts from agent output using `agent_config.parse_tool_output`
+- Capture file snapshots before/after execution using `State.capture_file_snapshot`
+- Detect files modified via `State.modified_files_since_snapshot`
+
+### 3. Data Extraction
+- Combine stdout/stderr for analysis
+- Detect completion promise using `::Ralph::Helpers.check_completion`
+- Extract errors from combined output using `::Ralph::Helpers.extract_errors`
+- Determine overall success status
+
+### 4. Result Packaging
+- Assemble all collected data into `IterationResult`
+- Return structured result to caller
+
+## External Dependencies (Provided by Caller)
+
+The class expects the caller to handle:
+- **Prompt Building** - Creating the prompt text using `PromptBuilder`
+- **Output Display** - Showing iteration summaries, warnings, etc.
+- **History Management** - Recording iteration data in `RalphHistory`
+- **State Updates** - Managing loop state, iteration counters
+- **Completion Decisions** - Determining whether to continue or break loop
+- **Error Handling** - Deciding how to respond to iteration errors
+- **Post-Processing** - Auto-committing changes, consuming context
+
+## Error Handling
+
+The `Iteration` class handles:
+- Process execution errors (captures in result)
+- Stream processing errors (captures in result)
+- File operation errors for snapshots (gracefully degrades)
+- Agent process cleanup if errors occur
+
+It does NOT:
+- Display error messages (caller responsibility)
+- Modify loop state (caller responsibility)
+- Make retry decisions (caller responsibility)
+
+## Usage Example
+
+```ruby
+# In Loop class (Loop exposes attr_reader :config, :agent_config)
+iteration = Iteration.new(self)
+
+result = iteration.call(full_prompt, iteration_start: start_time)
+
+# Caller processes result
+Output::IterationSummary.call(
+  iteration: @state.iteration,
+  elapsed_ms: result.duration_ms,
+  tool_counts: result.tool_counts,
+  exit_code: result.exit_code,
+  completion_detected: result.completion_detected
+)
+
+# Caller updates history
+record_iteration_in_history(result)
+
+# Caller decides what to do next
+if result.completion_detected && @state.iteration >= @min_iterations
+  # Handle completion
+end
+```
+
+## Implementation Notes
+
+### Thread Safety
+The class holds a reference to the parent `Loop` instance and mutable streaming state. It is not intended for concurrent use across multiple loops.
+
+### Performance Considerations
+- File snapshot operations should be efficient (git-based)
+- Stream processing should handle large outputs without memory issues
+- Tool counting should be done efficiently via line-by-line processing
+
+### Extensibility
+New config values are automatically available to `Iteration` via `@loop.config` without constructor changes.
+The `IterationResult` struct can be extended with additional fields as needed.
+
+## Testing Strategy
+
+### Unit Tests
+- Mock `Open3` to test agent execution logic
+- Mock `State` methods to test file snapshot logic
+- Test completion detection with various output formats
+- Test error extraction from different types of output
+- Test tool counting with different agent output formats
+
+### Integration Tests
+- Test with actual agent binaries (if available in test environment)
+- Test file snapshot operations with git repositories
+- Test streaming vs buffered output modes
+- Test error scenarios (agent crashes, git operations fail)
+
+## Migration Path
+
+1. Create the new `Iteration` class with this interface
+2. Update `Loop` class to use `Iteration` for agent execution
+3. Move iteration-related private methods from `Loop` to `Iteration`
+4. Update `Loop` to process `IterationResult` instead of handling execution directly
+5. Remove redundant code from `Loop` class
+6. Add tests for the new `Iteration` class
+
+This refactoring will improve separation of concerns, testability, and maintainability of the iteration execution logic.