[P2] Phase 2.2: Define custom tools for Agent SDK

[frankbria]

Description

Design and implement Ralph-specific custom tools for the Agent SDK.

Custom Tools to Implement

1. RateLimitTool

   • Check current API call count
   • Enforce call limits
   • Report remaining capacity

2. ExitDetectionTool

   • Analyze completion signals
   • Check @fix_plan.md completion
   • Report exit recommendations

3. CircuitBreakerTool

   • Monitor progress
   • Report stagnation
   • Recommend circuit breaker state

4. TaskPlannerTool

   • Read @fix_plan.md
   • Update task completion
   • Report progress

5. ProgressReporterTool

   • Update status.json
   • Log progress
   • Report metrics

Implementation Tasks

• Design tool interfaces
• Implement each custom tool
• Create tool registration system
• Add tool documentation
• Write tests for each tool
• Integrate with SDK wrapper

Dependencies

• Requires Phase 2.1 (SDK POC) to be complete

Acceptance Criteria

• All 5 custom tools implemented
• Tools integrate with Agent SDK
• Tools callable from SDK wrapper
• Tests pass for all tools
• Documentation complete

References

• Issue Review codebase for updated Anthropic CLI #7 - Phase 2.2

[traycerai]

Plan

Observations

Ralph is currently a bash-based autonomous development loop system (v0.9.0) with mature functionality including rate limiting, exit detection, circuit breaker patterns, and response analysis. The codebase has ~60% test coverage with 75 passing tests and uses modular library components (file:lib/circuit_breaker.sh, file:lib/response_analyzer.sh, file:lib/date_utils.sh). The project currently integrates with Claude Code CLI but lacks Agent SDK integration. The ticket references Phase 2.1 (SDK POC) as a dependency, suggesting a TypeScript/Node.js wrapper layer needs to be established first to bridge Ralph's bash implementation with the Anthropic Agent SDK's MCP server architecture.

Approach

The implementation will create a TypeScript-based MCP server layer that exposes Ralph's existing bash functionality as callable Agent SDK tools. Each of the 5 custom tools will wrap existing Ralph capabilities, executing shell commands and parsing JSON responses. The approach prioritizes reusing Ralph's battle-tested bash logic rather than rewriting it, ensuring consistency with the existing 75 passing tests. The tool registration system will use createSdkMcpServer and @tool decorators following Anthropic's MCP conventions, with tools named as mcp__ralph__{tool_name}. This design maintains Ralph's bash core while enabling Agent SDK integration for enhanced Claude Code workflows.

Implementation Steps

1. Prerequisites and Project Structure

Verify Phase 2.1 SDK POC Completion

• Confirm that Phase 2.1 (SDK POC) is complete and provides the base SDK wrapper infrastructure
• Review the SDK wrapper implementation to understand the integration points
• Identify the TypeScript/Node.js project structure established in Phase 2.1

Create SDK Tools Directory Structure

sdk/
├── src/
│   ├── tools/
│   │   ├── RateLimitTool.ts
│   │   ├── ExitDetectionTool.ts
│   │   ├── CircuitBreakerTool.ts
│   │   ├── TaskPlannerTool.ts
│   │   ├── ProgressReporterTool.ts
│   │   └── index.ts
│   ├── utils/
│   │   ├── shellExecutor.ts
│   │   ├── jsonParser.ts
│   │   └── errorHandler.ts
│   ├── types/
│   │   └── ralph.d.ts
│   └── server.ts
├── tests/
│   ├── tools/
│   │   ├── RateLimitTool.test.ts
│   │   ├── ExitDetectionTool.test.ts
│   │   ├── CircuitBreakerTool.test.ts
│   │   ├── TaskPlannerTool.test.ts
│   │   └── ProgressReporterTool.test.ts
│   └── integration/
│       └── mcpServer.test.ts
├── package.json
├── tsconfig.json
└── README.md

2. Design Tool Interfaces

Define TypeScript Types (file:sdk/src/types/ralph.d.ts)

• Create interfaces for each tool's input parameters and return types
• Define common types: RalphStatus, CallCount, ExitSignals, CircuitBreakerState, TaskList, ProgressMetrics
• Ensure type safety for shell command responses
• Document expected JSON schemas from bash scripts

Tool Interface Specifications

// RateLimitTool interface
interface RateLimitToolInput {
  action: 'check' | 'increment' | 'reset' | 'status';
}

interface RateLimitToolOutput {
  canMakeCall: boolean;
  currentCount: number;
  maxCalls: number;
  nextReset: string;
  remainingCapacity: number;
}

// ExitDetectionTool interface
interface ExitDetectionToolInput {
  action: 'check' | 'analyze' | 'signals';
}

interface ExitDetectionToolOutput {
  shouldExit: boolean;
  exitReason: string;
  confidence: number;
  signals: {
    testOnlyLoops: number[];
    doneSignals: number[];
    completionIndicators: number[];
  };
}

// CircuitBreakerTool interface
interface CircuitBreakerToolInput {
  action: 'status' | 'check' | 'reset' | 'record';
  loopNumber?: number;
  filesChanged?: number;
  hasErrors?: boolean;
  outputLength?: number;
}

interface CircuitBreakerToolOutput {
  state: 'CLOSED' | 'HALF_OPEN' | 'OPEN';
  canExecute: boolean;
  reason: string;
  consecutiveNoProgress: number;
  lastProgressLoop: number;
  totalOpens: number;
}

// TaskPlannerTool interface
interface TaskPlannerToolInput {
  action: 'read' | 'update' | 'progress';
  taskId?: string;
  completed?: boolean;
}

interface TaskPlannerToolOutput {
  totalTasks: number;
  completedTasks: number;
  pendingTasks: number;
  tasks: Array<{
    id: string;
    description: string;
    completed: boolean;
  }>;
  progressPercentage: number;
}

// ProgressReporterTool interface
interface ProgressReporterToolInput {
  action: 'update' | 'read' | 'metrics';
  status?: string;
  loopCount?: number;
  callsMade?: number;
}

interface ProgressReporterToolOutput {
  timestamp: string;
  loopCount: number;
  callsMade: number;
  status: string;
  metrics: {
    totalLoops: number;
    successfulLoops: number;
    failedLoops: number;
    averageDuration: number;
  };
}

3. Implement Utility Functions

Shell Executor (file:sdk/src/utils/shellExecutor.ts)

• Create executeShellCommand() function to run bash scripts safely
• Implement timeout handling for long-running commands
• Add proper error handling and stderr capture
• Support both synchronous and asynchronous execution
• Parse JSON output from bash scripts

JSON Parser (file:sdk/src/utils/jsonParser.ts)

• Create parseRalphJson() to safely parse JSON from bash script outputs
• Handle malformed JSON gracefully with fallback values
• Validate JSON against expected schemas
• Provide type-safe parsing with TypeScript generics

Error Handler (file:sdk/src/utils/errorHandler.ts)

• Create RalphToolError custom error class
• Implement error mapping from bash exit codes to meaningful messages
• Add logging for debugging tool execution failures
• Provide user-friendly error messages for Agent SDK

4. Implement RateLimitTool

Tool Implementation (file:sdk/src/tools/RateLimitTool.ts)

• Use @tool decorator to define the tool
• Implement check action: Execute can_make_call() from file:ralph_loop.sh
• Implement increment action: Call increment_call_counter()
• Implement reset action: Call init_call_tracking() with force reset
• Implement status action: Read file:.call_count and file:.last_reset files
• Calculate remaining capacity and next reset time
• Return structured RateLimitToolOutput

Integration Points

• Read from file:.call_count for current count
• Read from file:.last_reset for timestamp
• Use MAX_CALLS_PER_HOUR configuration from file:ralph_loop.sh
• Execute bash functions via shell executor utility

5. Implement ExitDetectionTool

Tool Implementation (file:sdk/src/tools/ExitDetectionTool.ts)

• Use @tool decorator to define the tool
• Implement check action: Execute should_exit_gracefully() from file:ralph_loop.sh
• Implement analyze action: Call analyze_response() from file:lib/response_analyzer.sh
• Implement signals action: Read and parse file:.exit_signals JSON
• Parse exit reasons: test_saturation, completion_signals, project_complete, plan_complete
• Return confidence scores and signal arrays

Integration Points

• Read file:.exit_signals for signal tracking
• Parse file:@fix_plan.md for task completion status
• Use file:.response_analysis for latest analysis results
• Execute should_exit_gracefully() bash function

6. Implement CircuitBreakerTool

Tool Implementation (file:sdk/src/tools/CircuitBreakerTool.ts)

• Use @tool decorator to define the tool
• Implement status action: Call show_circuit_status() from file:lib/circuit_breaker.sh
• Implement check action: Execute should_halt_execution()
• Implement reset action: Call reset_circuit_breaker()
• Implement record action: Call record_loop_result() with parameters
• Parse circuit breaker state from file:.circuit_breaker_state
• Return state transitions and history from file:.circuit_breaker_history

Integration Points

• Read file:.circuit_breaker_state for current state
• Read file:.circuit_breaker_history for transition log
• Execute circuit breaker functions from file:lib/circuit_breaker.sh
• Monitor thresholds: CB_NO_PROGRESS_THRESHOLD, CB_SAME_ERROR_THRESHOLD

7. Implement TaskPlannerTool

Tool Implementation (file:sdk/src/tools/TaskPlannerTool.ts)

• Use @tool decorator to define the tool
• Implement read action: Parse file:@fix_plan.md markdown checkboxes
• Implement update action: Modify checkbox state in file:@fix_plan.md
• Implement progress action: Calculate completion percentage
• Parse markdown format: - [ ] (pending) and - [x] (completed)
• Extract task descriptions and maintain task IDs
• Support atomic file updates to prevent corruption

Integration Points

• Read and write file:@fix_plan.md markdown file
• Parse checkbox syntax: - [ ] and - [x]
• Maintain task order and formatting
• Use grep patterns from should_exit_gracefully() in file:ralph_loop.sh

8. Implement ProgressReporterTool

Tool Implementation (file:sdk/src/tools/ProgressReporterTool.ts)

• Use @tool decorator to define the tool
• Implement update action: Call update_status() from file:ralph_loop.sh
• Implement read action: Parse file:status.json
• Implement metrics action: Aggregate metrics from logs and history
• Write to file:status.json with proper JSON formatting
• Append to file:logs/ralph.log with timestamps
• Calculate metrics: total loops, success rate, average duration

Integration Points

• Read and write file:status.json
• Append to file:logs/ralph.log
• Use update_status() function from file:ralph_loop.sh
• Parse file:progress.json for real-time progress
• Aggregate data from file:logs/ directory

9. Create Tool Registration System

MCP Server Setup (file:sdk/src/server.ts)

• Import createSdkMcpServer from Anthropic Agent SDK
• Register all 5 tools using the registration system
• Configure server name as ralph (tools will be mcp__ralph__{tool_name})
• Set up error handling and logging middleware
• Export server instance for integration with SDK wrapper

Tool Registration (file:sdk/src/tools/index.ts)

• Export all tool implementations
• Create registerRalphTools() function
• Map tool names to implementations
• Validate tool schemas at registration time
• Provide tool discovery endpoint

Configuration

• Add environment variables for Ralph home directory (RALPH_HOME)
• Support custom paths for Ralph installation
• Configure logging levels and output destinations
• Set timeouts for shell command execution

10. Add Documentation

Tool Documentation (file:sdk/README.md)

• Document each tool's purpose and capabilities
• Provide usage examples for each action
• Include input/output schema documentation
• Add troubleshooting guide for common issues
• Document integration with existing Ralph bash scripts

API Reference (file:sdk/docs/API.md)

• Complete API reference for all 5 tools
• Document all actions and parameters
• Include response schemas and error codes
• Provide code examples in TypeScript
• Document MCP tool naming convention

Integration Guide (file:sdk/docs/INTEGRATION.md)

• Explain how tools integrate with Ralph's bash core
• Document shell command execution patterns
• Describe JSON communication protocol
• Provide debugging tips
• Include architecture diagrams

11. Write Tests

Unit Tests (files in file:sdk/tests/tools/)

• Test each tool's actions independently
• Mock shell command execution
• Validate input parameter validation
• Test error handling scenarios
• Verify JSON parsing and type safety
• Aim for 85%+ code coverage per tool

Integration Tests (file:sdk/tests/integration/mcpServer.test.ts)

• Test tool registration with MCP server
• Verify tool discovery and invocation
• Test end-to-end workflows with actual bash scripts
• Validate JSON communication between layers
• Test concurrent tool execution
• Verify error propagation from bash to SDK

Test Utilities

• Create mock shell executor for unit tests
• Provide fixture data for Ralph state files
• Create helper functions for test setup/teardown
• Mock file system operations for isolated testing

12. Integration with SDK Wrapper

SDK Wrapper Integration (depends on Phase 2.1 structure)

• Import and register Ralph MCP server in SDK wrapper
• Configure server lifecycle management
• Add Ralph tools to Claude Code's available tools
• Test tool invocation from Claude Code
• Verify tool names follow mcp__ralph__{tool_name} format

Configuration Updates

• Update file:package.json with SDK dependencies
• Add build scripts for TypeScript compilation
• Configure test runners (Jest or similar)
• Set up linting and formatting (ESLint, Prettier)

Documentation Updates

• Update file:README.md with Agent SDK integration section
• Add SDK tools to feature list
• Document installation steps for SDK components
• Update file:CLAUDE.md with SDK tool usage patterns

Architecture Diagram

sequenceDiagram
    participant Claude as Claude Code
    participant SDK as Agent SDK
    participant MCP as Ralph MCP Server
    participant Tools as Ralph Tools
    participant Shell as Shell Executor
    participant Bash as Ralph Bash Scripts
    participant Files as State Files

    Claude->>SDK: Request tool execution
    SDK->>MCP: mcp__ralph__rate_limit
    MCP->>Tools: RateLimitTool.check()
    Tools->>Shell: executeShellCommand()
    Shell->>Bash: source ralph_loop.sh; can_make_call
    Bash->>Files: Read .call_count
    Files-->>Bash: Current count
    Bash-->>Shell: Exit code + stdout
    Shell-->>Tools: Parsed result
    Tools->>Tools: Parse JSON output
    Tools-->>MCP: RateLimitToolOutput
    MCP-->>SDK: Tool result
    SDK-->>Claude: Response with data

Loading

Tool Interaction Flow

graph TD
    A[Claude Code] -->|Calls tool| B[Agent SDK]
    B -->|Routes to| C[Ralph MCP Server]
    C -->|Dispatches| D{Tool Router}
    D -->|rate_limit| E[RateLimitTool]
    D -->|exit_detection| F[ExitDetectionTool]
    D -->|circuit_breaker| G[CircuitBreakerTool]
    D -->|task_planner| H[TaskPlannerTool]
    D -->|progress_reporter| I[ProgressReporterTool]
    E -->|Execute| J[Shell Executor]
    F -->|Execute| J
    G -->|Execute| J
    H -->|Execute| J
    I -->|Execute| J
    J -->|Run| K[Ralph Bash Scripts]
    K -->|Read/Write| L[State Files]
    L -->|Return| K
    K -->|Output| J
    J -->|Parse| E
    J -->|Parse| F
    J -->|Parse| G
    J -->|Parse| H
    J -->|Parse| I

Loading

Testing Strategy

Test Type	Coverage Target	Files
Unit Tests	85%+ per tool	file:sdk/tests/tools/*.test.ts
Integration Tests	Critical paths	file:sdk/tests/integration/*.test.ts
E2E Tests	Full workflows	Test with actual Ralph bash scripts
Type Safety	100%	TypeScript strict mode enabled

Dependencies

• Phase 2.1 (SDK POC): Must be complete before starting
• Node.js: v18+ for TypeScript and Agent SDK
• TypeScript: v5+ for type safety
• Anthropic Agent SDK: Latest version with MCP support
• Existing Ralph: v0.9.0 bash implementation
• Test Framework: Jest or Vitest for TypeScript testing

Success Criteria

• All 5 custom tools implemented and functional
• Tools successfully registered with Agent SDK MCP server
• Tools callable from Claude Code with proper naming (mcp__ralph__{tool_name})
• Unit tests pass with 85%+ coverage per tool
• Integration tests validate bash script communication
• Documentation complete with examples and API reference
• Tools integrate seamlessly with existing Ralph bash functionality
• No breaking changes to existing Ralph v0.9.0 behavior

Import In IDE

🤖 Prompt for AI Agents

## Observations

Ralph is currently a bash-based autonomous development loop system (v0.9.0) with mature functionality including rate limiting, exit detection, circuit breaker patterns, and response analysis. The codebase has ~60% test coverage with 75 passing tests and uses modular library components (`file:lib/circuit_breaker.sh`, `file:lib/response_analyzer.sh`, `file:lib/date_utils.sh`). The project currently integrates with Claude Code CLI but lacks Agent SDK integration. The ticket references Phase 2.1 (SDK POC) as a dependency, suggesting a TypeScript/Node.js wrapper layer needs to be established first to bridge Ralph's bash implementation with the Anthropic Agent SDK's MCP server architecture.

## Approach

The implementation will create a TypeScript-based MCP server layer that exposes Ralph's existing bash functionality as callable Agent SDK tools. Each of the 5 custom tools will wrap existing Ralph capabilities, executing shell commands and parsing JSON responses. The approach prioritizes reusing Ralph's battle-tested bash logic rather than rewriting it, ensuring consistency with the existing 75 passing tests. The tool registration system will use `createSdkMcpServer` and `@tool` decorators following Anthropic's MCP conventions, with tools named as `mcp__ralph__{tool_name}`. This design maintains Ralph's bash core while enabling Agent SDK integration for enhanced Claude Code workflows.

## Implementation Steps

### 1. Prerequisites and Project Structure

**Verify Phase 2.1 SDK POC Completion**
- Confirm that Phase 2.1 (SDK POC) is complete and provides the base SDK wrapper infrastructure
- Review the SDK wrapper implementation to understand the integration points
- Identify the TypeScript/Node.js project structure established in Phase 2.1

**Create SDK Tools Directory Structure**
```
sdk/
├── src/
│   ├── tools/
│   │   ├── RateLimitTool.ts
│   │   ├── ExitDetectionTool.ts
│   │   ├── CircuitBreakerTool.ts
│   │   ├── TaskPlannerTool.ts
│   │   ├── ProgressReporterTool.ts
│   │   └── index.ts
│   ├── utils/
│   │   ├── shellExecutor.ts
│   │   ├── jsonParser.ts
│   │   └── errorHandler.ts
│   ├── types/
│   │   └── ralph.d.ts
│   └── server.ts
├── tests/
│   ├── tools/
│   │   ├── RateLimitTool.test.ts
│   │   ├── ExitDetectionTool.test.ts
│   │   ├── CircuitBreakerTool.test.ts
│   │   ├── TaskPlannerTool.test.ts
│   │   └── ProgressReporterTool.test.ts
│   └── integration/
│       └── mcpServer.test.ts
├── package.json
├── tsconfig.json
└── README.md
```

### 2. Design Tool Interfaces

**Define TypeScript Types** (`file:sdk/src/types/ralph.d.ts`)
- Create interfaces for each tool's input parameters and return types
- Define common types: `RalphStatus`, `CallCount`, `ExitSignals`, `CircuitBreakerState`, `TaskList`, `ProgressMetrics`
- Ensure type safety for shell command responses
- Document expected JSON schemas from bash scripts

**Tool Interface Specifications**

```typescript
// RateLimitTool interface
interface RateLimitToolInput {
  action: 'check' | 'increment' | 'reset' | 'status';
}

interface RateLimitToolOutput {
  canMakeCall: boolean;
  currentCount: number;
  maxCalls: number;
  nextReset: string;
  remainingCapacity: number;
}

// ExitDetectionTool interface
interface ExitDetectionToolInput {
  action: 'check' | 'analyze' | 'signals';
}

interface ExitDetectionToolOutput {
  shouldExit: boolean;
  exitReason: string;
  confidence: number;
  signals: {
    testOnlyLoops: number[];
    doneSignals: number[];
    completionIndicators: number[];
  };
}

// CircuitBreakerTool interface
interface CircuitBreakerToolInput {
  action: 'status' | 'check' | 'reset' | 'record';
  loopNumber?: number;
  filesChanged?: number;
  hasErrors?: boolean;
  outputLength?: number;
}

interface CircuitBreakerToolOutput {
  state: 'CLOSED' | 'HALF_OPEN' | 'OPEN';
  canExecute: boolean;
  reason: string;
  consecutiveNoProgress: number;
  lastProgressLoop: number;
  totalOpens: number;
}

// TaskPlannerTool interface
interface TaskPlannerToolInput {
  action: 'read' | 'update' | 'progress';
  taskId?: string;
  completed?: boolean;
}

interface TaskPlannerToolOutput {
  totalTasks: number;
  completedTasks: number;
  pendingTasks: number;
  tasks: Array<{
    id: string;
    description: string;
    completed: boolean;
  }>;
  progressPercentage: number;
}

// ProgressReporterTool interface
interface ProgressReporterToolInput {
  action: 'update' | 'read' | 'metrics';
  status?: string;
  loopCount?: number;
  callsMade?: number;
}

interface ProgressReporterToolOutput {
  timestamp: string;
  loopCount: number;
  callsMade: number;
  status: string;
  metrics: {
    totalLoops: number;
    successfulLoops: number;
    failedLoops: number;
    averageDuration: number;
  };
}
```

### 3. Implement Utility Functions

**Shell Executor** (`file:sdk/src/utils/shellExecutor.ts`)
- Create `executeShellCommand()` function to run bash scripts safely
- Implement timeout handling for long-running commands
- Add proper error handling and stderr capture
- Support both synchronous and asynchronous execution
- Parse JSON output from bash scripts

**JSON Parser** (`file:sdk/src/utils/jsonParser.ts`)
- Create `parseRalphJson()` to safely parse JSON from bash script outputs
- Handle malformed JSON gracefully with fallback values
- Validate JSON against expected schemas
- Provide type-safe parsing with TypeScript generics

**Error Handler** (`file:sdk/src/utils/errorHandler.ts`)
- Create `RalphToolError` custom error class
- Implement error mapping from bash exit codes to meaningful messages
- Add logging for debugging tool execution failures
- Provide user-friendly error messages for Agent SDK

### 4. Implement RateLimitTool

**Tool Implementation** (`file:sdk/src/tools/RateLimitTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `check` action: Execute `can_make_call()` from `file:ralph_loop.sh`
- Implement `increment` action: Call `increment_call_counter()`
- Implement `reset` action: Call `init_call_tracking()` with force reset
- Implement `status` action: Read `file:.call_count` and `file:.last_reset` files
- Calculate remaining capacity and next reset time
- Return structured `RateLimitToolOutput`

**Integration Points**
- Read from `file:.call_count` for current count
- Read from `file:.last_reset` for timestamp
- Use `MAX_CALLS_PER_HOUR` configuration from `file:ralph_loop.sh`
- Execute bash functions via shell executor utility

### 5. Implement ExitDetectionTool

**Tool Implementation** (`file:sdk/src/tools/ExitDetectionTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `check` action: Execute `should_exit_gracefully()` from `file:ralph_loop.sh`
- Implement `analyze` action: Call `analyze_response()` from `file:lib/response_analyzer.sh`
- Implement `signals` action: Read and parse `file:.exit_signals` JSON
- Parse exit reasons: test_saturation, completion_signals, project_complete, plan_complete
- Return confidence scores and signal arrays

**Integration Points**
- Read `file:.exit_signals` for signal tracking
- Parse `file:@fix_plan.md` for task completion status
- Use `file:.response_analysis` for latest analysis results
- Execute `should_exit_gracefully()` bash function

### 6. Implement CircuitBreakerTool

**Tool Implementation** (`file:sdk/src/tools/CircuitBreakerTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `status` action: Call `show_circuit_status()` from `file:lib/circuit_breaker.sh`
- Implement `check` action: Execute `should_halt_execution()`
- Implement `reset` action: Call `reset_circuit_breaker()`
- Implement `record` action: Call `record_loop_result()` with parameters
- Parse circuit breaker state from `file:.circuit_breaker_state`
- Return state transitions and history from `file:.circuit_breaker_history`

**Integration Points**
- Read `file:.circuit_breaker_state` for current state
- Read `file:.circuit_breaker_history` for transition log
- Execute circuit breaker functions from `file:lib/circuit_breaker.sh`
- Monitor thresholds: `CB_NO_PROGRESS_THRESHOLD`, `CB_SAME_ERROR_THRESHOLD`

### 7. Implement TaskPlannerTool

**Tool Implementation** (`file:sdk/src/tools/TaskPlannerTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `read` action: Parse `file:@fix_plan.md` markdown checkboxes
- Implement `update` action: Modify checkbox state in `file:@fix_plan.md`
- Implement `progress` action: Calculate completion percentage
- Parse markdown format: `- [ ]` (pending) and `- [x]` (completed)
- Extract task descriptions and maintain task IDs
- Support atomic file updates to prevent corruption

**Integration Points**
- Read and write `file:@fix_plan.md` markdown file
- Parse checkbox syntax: `- [ ]` and `- [x]`
- Maintain task order and formatting
- Use `grep` patterns from `should_exit_gracefully()` in `file:ralph_loop.sh`

### 8. Implement ProgressReporterTool

**Tool Implementation** (`file:sdk/src/tools/ProgressReporterTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `update` action: Call `update_status()` from `file:ralph_loop.sh`
- Implement `read` action: Parse `file:status.json`
- Implement `metrics` action: Aggregate metrics from logs and history
- Write to `file:status.json` with proper JSON formatting
- Append to `file:logs/ralph.log` with timestamps
- Calculate metrics: total loops, success rate, average duration

**Integration Points**
- Read and write `file:status.json`
- Append to `file:logs/ralph.log`
- Use `update_status()` function from `file:ralph_loop.sh`
- Parse `file:progress.json` for real-time progress
- Aggregate data from `file:logs/` directory

### 9. Create Tool Registration System

**MCP Server Setup** (`file:sdk/src/server.ts`)
- Import `createSdkMcpServer` from Anthropic Agent SDK
- Register all 5 tools using the registration system
- Configure server name as `ralph` (tools will be `mcp__ralph__{tool_name}`)
- Set up error handling and logging middleware
- Export server instance for integration with SDK wrapper

**Tool Registration** (`file:sdk/src/tools/index.ts`)
- Export all tool implementations
- Create `registerRalphTools()` function
- Map tool names to implementations
- Validate tool schemas at registration time
- Provide tool discovery endpoint

**Configuration**
- Add environment variables for Ralph home directory (`RALPH_HOME`)
- Support custom paths for Ralph installation
- Configure logging levels and output destinations
- Set timeouts for shell command execution

### 10. Add Documentation

**Tool Documentation** (`file:sdk/README.md`)
- Document each tool's purpose and capabilities
- Provide usage examples for each action
- Include input/output schema documentation
- Add troubleshooting guide for common issues
- Document integration with existing Ralph bash scripts

**API Reference** (`file:sdk/docs/API.md`)
- Complete API reference for all 5 tools
- Document all actions and parameters
- Include response schemas and error codes
- Provide code examples in TypeScript
- Document MCP tool naming convention

**Integration Guide** (`file:sdk/docs/INTEGRATION.md`)
- Explain how tools integrate with Ralph's bash core
- Document shell command execution patterns
- Describe JSON communication protocol
- Provide debugging tips
- Include architecture diagrams

### 11. Write Tests

**Unit Tests** (files in `file:sdk/tests/tools/`)
- Test each tool's actions independently
- Mock shell command execution
- Validate input parameter validation
- Test error handling scenarios
- Verify JSON parsing and type safety
- Aim for 85%+ code coverage per tool

**Integration Tests** (`file:sdk/tests/integration/mcpServer.test.ts`)
- Test tool registration with MCP server
- Verify tool discovery and invocation
- Test end-to-end workflows with actual bash scripts
- Validate JSON communication between layers
- Test concurrent tool execution
- Verify error propagation from bash to SDK

**Test Utilities**
- Create mock shell executor for unit tests
- Provide fixture data for Ralph state files
- Create helper functions for test setup/teardown
- Mock file system operations for isolated testing

### 12. Integration with SDK Wrapper

**SDK Wrapper Integration** (depends on Phase 2.1 structure)
- Import and register Ralph MCP server in SDK wrapper
- Configure server lifecycle management
- Add Ralph tools to Claude Code's available tools
- Test tool invocation from Claude Code
- Verify tool names follow `mcp__ralph__{tool_name}` format

**Configuration Updates**
- Update `file:package.json` with SDK dependencies
- Add build scripts for TypeScript compilation
- Configure test runners (Jest or similar)
- Set up linting and formatting (ESLint, Prettier)

**Documentation Updates**
- Update `file:README.md` with Agent SDK integration section
- Add SDK tools to feature list
- Document installation steps for SDK components
- Update `file:CLAUDE.md` with SDK tool usage patterns

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Claude as Claude Code
    participant SDK as Agent SDK
    participant MCP as Ralph MCP Server
    participant Tools as Ralph Tools
    participant Shell as Shell Executor
    participant Bash as Ralph Bash Scripts
    participant Files as State Files

    Claude->>SDK: Request tool execution
    SDK->>MCP: mcp__ralph__rate_limit
    MCP->>Tools: RateLimitTool.check()
    Tools->>Shell: executeShellCommand()
    Shell->>Bash: source ralph_loop.sh; can_make_call
    Bash->>Files: Read .call_count
    Files-->>Bash: Current count
    Bash-->>Shell: Exit code + stdout
    Shell-->>Tools: Parsed result
    Tools->>Tools: Parse JSON output
    Tools-->>MCP: RateLimitToolOutput
    MCP-->>SDK: Tool result
    SDK-->>Claude: Response with data
```

## Tool Interaction Flow

```mermaid
graph TD
    A[Claude Code] -->|Calls tool| B[Agent SDK]
    B -->|Routes to| C[Ralph MCP Server]
    C -->|Dispatches| D{Tool Router}
    D -->|rate_limit| E[RateLimitTool]
    D -->|exit_detection| F[ExitDetectionTool]
    D -->|circuit_breaker| G[CircuitBreakerTool]
    D -->|task_planner| H[TaskPlannerTool]
    D -->|progress_reporter| I[ProgressReporterTool]
    E -->|Execute| J[Shell Executor]
    F -->|Execute| J
    G -->|Execute| J
    H -->|Execute| J
    I -->|Execute| J
    J -->|Run| K[Ralph Bash Scripts]
    K -->|Read/Write| L[State Files]
    L -->|Return| K
    K -->|Output| J
    J -->|Parse| E
    J -->|Parse| F
    J -->|Parse| G
    J -->|Parse| H
    J -->|Parse| I
```

## Testing Strategy

| Test Type | Coverage Target | Files |
|-----------|----------------|-------|
| Unit Tests | 85%+ per tool | `file:sdk/tests/tools/*.test.ts` |
| Integration Tests | Critical paths | `file:sdk/tests/integration/*.test.ts` |
| E2E Tests | Full workflows | Test with actual Ralph bash scripts |
| Type Safety | 100% | TypeScript strict mode enabled |

## Dependencies

- **Phase 2.1 (SDK POC)**: Must be complete before starting
- **Node.js**: v18+ for TypeScript and Agent SDK
- **TypeScript**: v5+ for type safety
- **Anthropic Agent SDK**: Latest version with MCP support
- **Existing Ralph**: v0.9.0 bash implementation
- **Test Framework**: Jest or Vitest for TypeScript testing

## Success Criteria

- All 5 custom tools implemented and functional
- Tools successfully registered with Agent SDK MCP server
- Tools callable from Claude Code with proper naming (`mcp__ralph__{tool_name}`)
- Unit tests pass with 85%+ coverage per tool
- Integration tests validate bash script communication
- Documentation complete with examples and API reference
- Tools integrate seamlessly with existing Ralph bash functionality
- No breaking changes to existing Ralph v0.9.0 behavior

---

Execution Information

Branch: main
Commit: 870181b

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• [P2] Phase 2.1: Create Agent SDK proof of concept #32
• [P1] Phase 1.4: Update ralph-import with CLI enhancements #31
• [P3] Phase 4.7: Implement E2E full loop tests #17

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

Ralph is currently a bash-based autonomous development loop system (v0.9.0) with mature functionality including rate limiting, exit detection, circuit breaker patterns, and response analysis. The codebase has ~60% test coverage with 75 passing tests and uses modular library components (file:lib/circuit_breaker.sh, file:lib/response_analyzer.sh, file:lib/date_utils.sh). The project currently integrates with Claude Code CLI but lacks Agent SDK integration. The ticket references Phase 2.1 (SDK POC) as a dependency, suggesting a TypeScript/Node.js wrapper layer needs to be established first to bridge Ralph's bash implementation with the Anthropic Agent SDK's MCP server architecture.

Approach

The implementation will create a TypeScript-based MCP server layer that exposes Ralph's existing bash functionality as callable Agent SDK tools. Each of the 5 custom tools will wrap existing Ralph capabilities, executing shell commands and parsing JSON responses. The approach prioritizes reusing Ralph's battle-tested bash logic rather than rewriting it, ensuring consistency with the existing 75 passing tests. The tool registration system will use createSdkMcpServer and @tool decorators following Anthropic's MCP conventions, with tools named as mcp__ralph__{tool_name}. This design maintains Ralph's bash core while enabling Agent SDK integration for enhanced Claude Code workflows.

Implementation Steps

1. Prerequisites and Project Structure

Verify Phase 2.1 SDK POC Completion

• Confirm that Phase 2.1 (SDK POC) is complete and provides the base SDK wrapper infrastructure
• Review the SDK wrapper implementation to understand the integration points
• Identify the TypeScript/Node.js project structure established in Phase 2.1

Create SDK Tools Directory Structure

sdk/
├── src/
│   ├── tools/
│   │   ├── RateLimitTool.ts
│   │   ├── ExitDetectionTool.ts
│   │   ├── CircuitBreakerTool.ts
│   │   ├── TaskPlannerTool.ts
│   │   ├── ProgressReporterTool.ts
│   │   └── index.ts
│   ├── utils/
│   │   ├── shellExecutor.ts
│   │   ├── jsonParser.ts
│   │   └── errorHandler.ts
│   ├── types/
│   │   └── ralph.d.ts
│   └── server.ts
├── tests/
│   ├── tools/
│   │   ├── RateLimitTool.test.ts
│   │   ├── ExitDetectionTool.test.ts
│   │   ├── CircuitBreakerTool.test.ts
│   │   ├── TaskPlannerTool.test.ts
│   │   └── ProgressReporterTool.test.ts
│   └── integration/
│       └── mcpServer.test.ts
├── package.json
├── tsconfig.json
└── README.md

2. Design Tool Interfaces

Define TypeScript Types (file:sdk/src/types/ralph.d.ts)

• Create interfaces for each tool's input parameters and return types
• Define common types: RalphStatus, CallCount, ExitSignals, CircuitBreakerState, TaskList, ProgressMetrics
• Ensure type safety for shell command responses
• Document expected JSON schemas from bash scripts

Tool Interface Specifications

// RateLimitTool interface
interface RateLimitToolInput {
  action: 'check' | 'increment' | 'reset' | 'status';
}

interface RateLimitToolOutput {
  canMakeCall: boolean;
  currentCount: number;
  maxCalls: number;
  nextReset: string;
  remainingCapacity: number;
}

// ExitDetectionTool interface
interface ExitDetectionToolInput {
  action: 'check' | 'analyze' | 'signals';
}

interface ExitDetectionToolOutput {
  shouldExit: boolean;
  exitReason: string;
  confidence: number;
  signals: {
    testOnlyLoops: number[];
    doneSignals: number[];
    completionIndicators: number[];
  };
}

// CircuitBreakerTool interface
interface CircuitBreakerToolInput {
  action: 'status' | 'check' | 'reset' | 'record';
  loopNumber?: number;
  filesChanged?: number;
  hasErrors?: boolean;
  outputLength?: number;
}

interface CircuitBreakerToolOutput {
  state: 'CLOSED' | 'HALF_OPEN' | 'OPEN';
  canExecute: boolean;
  reason: string;
  consecutiveNoProgress: number;
  lastProgressLoop: number;
  totalOpens: number;
}

// TaskPlannerTool interface
interface TaskPlannerToolInput {
  action: 'read' | 'update' | 'progress';
  taskId?: string;
  completed?: boolean;
}

interface TaskPlannerToolOutput {
  totalTasks: number;
  completedTasks: number;
  pendingTasks: number;
  tasks: Array<{
    id: string;
    description: string;
    completed: boolean;
  }>;
  progressPercentage: number;
}

// ProgressReporterTool interface
interface ProgressReporterToolInput {
  action: 'update' | 'read' | 'metrics';
  status?: string;
  loopCount?: number;
  callsMade?: number;
}

interface ProgressReporterToolOutput {
  timestamp: string;
  loopCount: number;
  callsMade: number;
  status: string;
  metrics: {
    totalLoops: number;
    successfulLoops: number;
    failedLoops: number;
    averageDuration: number;
  };
}

3. Implement Utility Functions

Shell Executor (file:sdk/src/utils/shellExecutor.ts)

• Create executeShellCommand() function to run bash scripts safely
• Implement timeout handling for long-running commands
• Add proper error handling and stderr capture
• Support both synchronous and asynchronous execution
• Parse JSON output from bash scripts

JSON Parser (file:sdk/src/utils/jsonParser.ts)

• Create parseRalphJson() to safely parse JSON from bash script outputs
• Handle malformed JSON gracefully with fallback values
• Validate JSON against expected schemas
• Provide type-safe parsing with TypeScript generics

Error Handler (file:sdk/src/utils/errorHandler.ts)

• Create RalphToolError custom error class
• Implement error mapping from bash exit codes to meaningful messages
• Add logging for debugging tool execution failures
• Provide user-friendly error messages for Agent SDK

4. Implement RateLimitTool

Tool Implementation (file:sdk/src/tools/RateLimitTool.ts)

• Use @tool decorator to define the tool
• Implement check action: Execute can_make_call() from file:ralph_loop.sh
• Implement increment action: Call increment_call_counter()
• Implement reset action: Call init_call_tracking() with force reset
• Implement status action: Read file:.call_count and file:.last_reset files
• Calculate remaining capacity and next reset time
• Return structured RateLimitToolOutput

Integration Points

• Read from file:.call_count for current count
• Read from file:.last_reset for timestamp
• Use MAX_CALLS_PER_HOUR configuration from file:ralph_loop.sh
• Execute bash functions via shell executor utility

5. Implement ExitDetectionTool

Tool Implementation (file:sdk/src/tools/ExitDetectionTool.ts)

• Use @tool decorator to define the tool
• Implement check action: Execute should_exit_gracefully() from file:ralph_loop.sh
• Implement analyze action: Call analyze_response() from file:lib/response_analyzer.sh
• Implement signals action: Read and parse file:.exit_signals JSON
• Parse exit reasons: test_saturation, completion_signals, project_complete, plan_complete
• Return confidence scores and signal arrays

Integration Points

• Read file:.exit_signals for signal tracking
• Parse file:@fix_plan.md for task completion status
• Use file:.response_analysis for latest analysis results
• Execute should_exit_gracefully() bash function

6. Implement CircuitBreakerTool

Tool Implementation (file:sdk/src/tools/CircuitBreakerTool.ts)

• Use @tool decorator to define the tool
• Implement status action: Call show_circuit_status() from file:lib/circuit_breaker.sh
• Implement check action: Execute should_halt_execution()
• Implement reset action: Call reset_circuit_breaker()
• Implement record action: Call record_loop_result() with parameters
• Parse circuit breaker state from file:.circuit_breaker_state
• Return state transitions and history from file:.circuit_breaker_history

Integration Points

• Read file:.circuit_breaker_state for current state
• Read file:.circuit_breaker_history for transition log
• Execute circuit breaker functions from file:lib/circuit_breaker.sh
• Monitor thresholds: CB_NO_PROGRESS_THRESHOLD, CB_SAME_ERROR_THRESHOLD

7. Implement TaskPlannerTool

Tool Implementation (file:sdk/src/tools/TaskPlannerTool.ts)

• Use @tool decorator to define the tool
• Implement read action: Parse file:@fix_plan.md markdown checkboxes
• Implement update action: Modify checkbox state in file:@fix_plan.md
• Implement progress action: Calculate completion percentage
• Parse markdown format: - [ ] (pending) and - [x] (completed)
• Extract task descriptions and maintain task IDs
• Support atomic file updates to prevent corruption

Integration Points

• Read and write file:@fix_plan.md markdown file
• Parse checkbox syntax: - [ ] and - [x]
• Maintain task order and formatting
• Use grep patterns from should_exit_gracefully() in file:ralph_loop.sh

8. Implement ProgressReporterTool

Tool Implementation (file:sdk/src/tools/ProgressReporterTool.ts)

• Use @tool decorator to define the tool
• Implement update action: Call update_status() from file:ralph_loop.sh
• Implement read action: Parse file:status.json
• Implement metrics action: Aggregate metrics from logs and history
• Write to file:status.json with proper JSON formatting
• Append to file:logs/ralph.log with timestamps
• Calculate metrics: total loops, success rate, average duration

Integration Points

• Read and write file:status.json
• Append to file:logs/ralph.log
• Use update_status() function from file:ralph_loop.sh
• Parse file:progress.json for real-time progress
• Aggregate data from file:logs/ directory

9. Create Tool Registration System

MCP Server Setup (file:sdk/src/server.ts)

• Import createSdkMcpServer from Anthropic Agent SDK
• Register all 5 tools using the registration system
• Configure server name as ralph (tools will be mcp__ralph__{tool_name})
• Set up error handling and logging middleware
• Export server instance for integration with SDK wrapper

Tool Registration (file:sdk/src/tools/index.ts)

• Export all tool implementations
• Create registerRalphTools() function
• Map tool names to implementations
• Validate tool schemas at registration time
• Provide tool discovery endpoint

Configuration

• Add environment variables for Ralph home directory (RALPH_HOME)
• Support custom paths for Ralph installation
• Configure logging levels and output destinations
• Set timeouts for shell command execution

10. Add Documentation

Tool Documentation (file:sdk/README.md)

• Document each tool's purpose and capabilities
• Provide usage examples for each action
• Include input/output schema documentation
• Add troubleshooting guide for common issues
• Document integration with existing Ralph bash scripts

API Reference (file:sdk/docs/API.md)

• Complete API reference for all 5 tools
• Document all actions and parameters
• Include response schemas and error codes
• Provide code examples in TypeScript
• Document MCP tool naming convention

Integration Guide (file:sdk/docs/INTEGRATION.md)

• Explain how tools integrate with Ralph's bash core
• Document shell command execution patterns
• Describe JSON communication protocol
• Provide debugging tips
• Include architecture diagrams

11. Write Tests

Unit Tests (files in file:sdk/tests/tools/)

• Test each tool's actions independently
• Mock shell command execution
• Validate input parameter validation
• Test error handling scenarios
• Verify JSON parsing and type safety
• Aim for 85%+ code coverage per tool

Integration Tests (file:sdk/tests/integration/mcpServer.test.ts)

• Test tool registration with MCP server
• Verify tool discovery and invocation
• Test end-to-end workflows with actual bash scripts
• Validate JSON communication between layers
• Test concurrent tool execution
• Verify error propagation from bash to SDK

Test Utilities

• Create mock shell executor for unit tests
• Provide fixture data for Ralph state files
• Create helper functions for test setup/teardown
• Mock file system operations for isolated testing

12. Integration with SDK Wrapper

SDK Wrapper Integration (depends on Phase 2.1 structure)

• Import and register Ralph MCP server in SDK wrapper
• Configure server lifecycle management
• Add Ralph tools to Claude Code's available tools
• Test tool invocation from Claude Code
• Verify tool names follow mcp__ralph__{tool_name} format

Configuration Updates

• Update file:package.json with SDK dependencies
• Add build scripts for TypeScript compilation
• Configure test runners (Jest or similar)
• Set up linting and formatting (ESLint, Prettier)

Documentation Updates

• Update file:README.md with Agent SDK integration section
• Add SDK tools to feature list
• Document installation steps for SDK components
• Update file:CLAUDE.md with SDK tool usage patterns

Architecture Diagram

sequenceDiagram
    participant Claude as Claude Code
    participant SDK as Agent SDK
    participant MCP as Ralph MCP Server
    participant Tools as Ralph Tools
    participant Shell as Shell Executor
    participant Bash as Ralph Bash Scripts
    participant Files as State Files

    Claude->>SDK: Request tool execution
    SDK->>MCP: mcp__ralph__rate_limit
    MCP->>Tools: RateLimitTool.check()
    Tools->>Shell: executeShellCommand()
    Shell->>Bash: source ralph_loop.sh; can_make_call
    Bash->>Files: Read .call_count
    Files-->>Bash: Current count
    Bash-->>Shell: Exit code + stdout
    Shell-->>Tools: Parsed result
    Tools->>Tools: Parse JSON output
    Tools-->>MCP: RateLimitToolOutput
    MCP-->>SDK: Tool result
    SDK-->>Claude: Response with data

Loading

Tool Interaction Flow

graph TD
    A[Claude Code] -->|Calls tool| B[Agent SDK]
    B -->|Routes to| C[Ralph MCP Server]
    C -->|Dispatches| D{Tool Router}
    D -->|rate_limit| E[RateLimitTool]
    D -->|exit_detection| F[ExitDetectionTool]
    D -->|circuit_breaker| G[CircuitBreakerTool]
    D -->|task_planner| H[TaskPlannerTool]
    D -->|progress_reporter| I[ProgressReporterTool]
    E -->|Execute| J[Shell Executor]
    F -->|Execute| J
    G -->|Execute| J
    H -->|Execute| J
    I -->|Execute| J
    J -->|Run| K[Ralph Bash Scripts]
    K -->|Read/Write| L[State Files]
    L -->|Return| K
    K -->|Output| J
    J -->|Parse| E
    J -->|Parse| F
    J -->|Parse| G
    J -->|Parse| H
    J -->|Parse| I

Loading

Testing Strategy

Test Type	Coverage Target	Files
Unit Tests	85%+ per tool	file:sdk/tests/tools/*.test.ts
Integration Tests	Critical paths	file:sdk/tests/integration/*.test.ts
E2E Tests	Full workflows	Test with actual Ralph bash scripts
Type Safety	100%	TypeScript strict mode enabled

Dependencies

• Phase 2.1 (SDK POC): Must be complete before starting
• Node.js: v18+ for TypeScript and Agent SDK
• TypeScript: v5+ for type safety
• Anthropic Agent SDK: Latest version with MCP support
• Existing Ralph: v0.9.0 bash implementation
• Test Framework: Jest or Vitest for TypeScript testing

Success Criteria

• All 5 custom tools implemented and functional
• Tools successfully registered with Agent SDK MCP server
• Tools callable from Claude Code with proper naming (mcp__ralph__{tool_name})
• Unit tests pass with 85%+ coverage per tool
• Integration tests validate bash script communication
• Documentation complete with examples and API reference
• Tools integrate seamlessly with existing Ralph bash functionality
• No breaking changes to existing Ralph v0.9.0 behavior

Import In IDE

🤖 Prompt for AI Agents

## Observations

Ralph is currently a bash-based autonomous development loop system (v0.9.0) with mature functionality including rate limiting, exit detection, circuit breaker patterns, and response analysis. The codebase has ~60% test coverage with 75 passing tests and uses modular library components (`file:lib/circuit_breaker.sh`, `file:lib/response_analyzer.sh`, `file:lib/date_utils.sh`). The project currently integrates with Claude Code CLI but lacks Agent SDK integration. The ticket references Phase 2.1 (SDK POC) as a dependency, suggesting a TypeScript/Node.js wrapper layer needs to be established first to bridge Ralph's bash implementation with the Anthropic Agent SDK's MCP server architecture.

## Approach

The implementation will create a TypeScript-based MCP server layer that exposes Ralph's existing bash functionality as callable Agent SDK tools. Each of the 5 custom tools will wrap existing Ralph capabilities, executing shell commands and parsing JSON responses. The approach prioritizes reusing Ralph's battle-tested bash logic rather than rewriting it, ensuring consistency with the existing 75 passing tests. The tool registration system will use `createSdkMcpServer` and `@tool` decorators following Anthropic's MCP conventions, with tools named as `mcp__ralph__{tool_name}`. This design maintains Ralph's bash core while enabling Agent SDK integration for enhanced Claude Code workflows.

## Implementation Steps

### 1. Prerequisites and Project Structure

**Verify Phase 2.1 SDK POC Completion**
- Confirm that Phase 2.1 (SDK POC) is complete and provides the base SDK wrapper infrastructure
- Review the SDK wrapper implementation to understand the integration points
- Identify the TypeScript/Node.js project structure established in Phase 2.1

**Create SDK Tools Directory Structure**
```
sdk/
├── src/
│   ├── tools/
│   │   ├── RateLimitTool.ts
│   │   ├── ExitDetectionTool.ts
│   │   ├── CircuitBreakerTool.ts
│   │   ├── TaskPlannerTool.ts
│   │   ├── ProgressReporterTool.ts
│   │   └── index.ts
│   ├── utils/
│   │   ├── shellExecutor.ts
│   │   ├── jsonParser.ts
│   │   └── errorHandler.ts
│   ├── types/
│   │   └── ralph.d.ts
│   └── server.ts
├── tests/
│   ├── tools/
│   │   ├── RateLimitTool.test.ts
│   │   ├── ExitDetectionTool.test.ts
│   │   ├── CircuitBreakerTool.test.ts
│   │   ├── TaskPlannerTool.test.ts
│   │   └── ProgressReporterTool.test.ts
│   └── integration/
│       └── mcpServer.test.ts
├── package.json
├── tsconfig.json
└── README.md
```

### 2. Design Tool Interfaces

**Define TypeScript Types** (`file:sdk/src/types/ralph.d.ts`)
- Create interfaces for each tool's input parameters and return types
- Define common types: `RalphStatus`, `CallCount`, `ExitSignals`, `CircuitBreakerState`, `TaskList`, `ProgressMetrics`
- Ensure type safety for shell command responses
- Document expected JSON schemas from bash scripts

**Tool Interface Specifications**

```typescript
// RateLimitTool interface
interface RateLimitToolInput {
  action: 'check' | 'increment' | 'reset' | 'status';
}

interface RateLimitToolOutput {
  canMakeCall: boolean;
  currentCount: number;
  maxCalls: number;
  nextReset: string;
  remainingCapacity: number;
}

// ExitDetectionTool interface
interface ExitDetectionToolInput {
  action: 'check' | 'analyze' | 'signals';
}

interface ExitDetectionToolOutput {
  shouldExit: boolean;
  exitReason: string;
  confidence: number;
  signals: {
    testOnlyLoops: number[];
    doneSignals: number[];
    completionIndicators: number[];
  };
}

// CircuitBreakerTool interface
interface CircuitBreakerToolInput {
  action: 'status' | 'check' | 'reset' | 'record';
  loopNumber?: number;
  filesChanged?: number;
  hasErrors?: boolean;
  outputLength?: number;
}

interface CircuitBreakerToolOutput {
  state: 'CLOSED' | 'HALF_OPEN' | 'OPEN';
  canExecute: boolean;
  reason: string;
  consecutiveNoProgress: number;
  lastProgressLoop: number;
  totalOpens: number;
}

// TaskPlannerTool interface
interface TaskPlannerToolInput {
  action: 'read' | 'update' | 'progress';
  taskId?: string;
  completed?: boolean;
}

interface TaskPlannerToolOutput {
  totalTasks: number;
  completedTasks: number;
  pendingTasks: number;
  tasks: Array<{
    id: string;
    description: string;
    completed: boolean;
  }>;
  progressPercentage: number;
}

// ProgressReporterTool interface
interface ProgressReporterToolInput {
  action: 'update' | 'read' | 'metrics';
  status?: string;
  loopCount?: number;
  callsMade?: number;
}

interface ProgressReporterToolOutput {
  timestamp: string;
  loopCount: number;
  callsMade: number;
  status: string;
  metrics: {
    totalLoops: number;
    successfulLoops: number;
    failedLoops: number;
    averageDuration: number;
  };
}
```

### 3. Implement Utility Functions

**Shell Executor** (`file:sdk/src/utils/shellExecutor.ts`)
- Create `executeShellCommand()` function to run bash scripts safely
- Implement timeout handling for long-running commands
- Add proper error handling and stderr capture
- Support both synchronous and asynchronous execution
- Parse JSON output from bash scripts

**JSON Parser** (`file:sdk/src/utils/jsonParser.ts`)
- Create `parseRalphJson()` to safely parse JSON from bash script outputs
- Handle malformed JSON gracefully with fallback values
- Validate JSON against expected schemas
- Provide type-safe parsing with TypeScript generics

**Error Handler** (`file:sdk/src/utils/errorHandler.ts`)
- Create `RalphToolError` custom error class
- Implement error mapping from bash exit codes to meaningful messages
- Add logging for debugging tool execution failures
- Provide user-friendly error messages for Agent SDK

### 4. Implement RateLimitTool

**Tool Implementation** (`file:sdk/src/tools/RateLimitTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `check` action: Execute `can_make_call()` from `file:ralph_loop.sh`
- Implement `increment` action: Call `increment_call_counter()`
- Implement `reset` action: Call `init_call_tracking()` with force reset
- Implement `status` action: Read `file:.call_count` and `file:.last_reset` files
- Calculate remaining capacity and next reset time
- Return structured `RateLimitToolOutput`

**Integration Points**
- Read from `file:.call_count` for current count
- Read from `file:.last_reset` for timestamp
- Use `MAX_CALLS_PER_HOUR` configuration from `file:ralph_loop.sh`
- Execute bash functions via shell executor utility

### 5. Implement ExitDetectionTool

**Tool Implementation** (`file:sdk/src/tools/ExitDetectionTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `check` action: Execute `should_exit_gracefully()` from `file:ralph_loop.sh`
- Implement `analyze` action: Call `analyze_response()` from `file:lib/response_analyzer.sh`
- Implement `signals` action: Read and parse `file:.exit_signals` JSON
- Parse exit reasons: test_saturation, completion_signals, project_complete, plan_complete
- Return confidence scores and signal arrays

**Integration Points**
- Read `file:.exit_signals` for signal tracking
- Parse `file:@fix_plan.md` for task completion status
- Use `file:.response_analysis` for latest analysis results
- Execute `should_exit_gracefully()` bash function

### 6. Implement CircuitBreakerTool

**Tool Implementation** (`file:sdk/src/tools/CircuitBreakerTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `status` action: Call `show_circuit_status()` from `file:lib/circuit_breaker.sh`
- Implement `check` action: Execute `should_halt_execution()`
- Implement `reset` action: Call `reset_circuit_breaker()`
- Implement `record` action: Call `record_loop_result()` with parameters
- Parse circuit breaker state from `file:.circuit_breaker_state`
- Return state transitions and history from `file:.circuit_breaker_history`

**Integration Points**
- Read `file:.circuit_breaker_state` for current state
- Read `file:.circuit_breaker_history` for transition log
- Execute circuit breaker functions from `file:lib/circuit_breaker.sh`
- Monitor thresholds: `CB_NO_PROGRESS_THRESHOLD`, `CB_SAME_ERROR_THRESHOLD`

### 7. Implement TaskPlannerTool

**Tool Implementation** (`file:sdk/src/tools/TaskPlannerTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `read` action: Parse `file:@fix_plan.md` markdown checkboxes
- Implement `update` action: Modify checkbox state in `file:@fix_plan.md`
- Implement `progress` action: Calculate completion percentage
- Parse markdown format: `- [ ]` (pending) and `- [x]` (completed)
- Extract task descriptions and maintain task IDs
- Support atomic file updates to prevent corruption

**Integration Points**
- Read and write `file:@fix_plan.md` markdown file
- Parse checkbox syntax: `- [ ]` and `- [x]`
- Maintain task order and formatting
- Use `grep` patterns from `should_exit_gracefully()` in `file:ralph_loop.sh`

### 8. Implement ProgressReporterTool

**Tool Implementation** (`file:sdk/src/tools/ProgressReporterTool.ts`)
- Use `@tool` decorator to define the tool
- Implement `update` action: Call `update_status()` from `file:ralph_loop.sh`
- Implement `read` action: Parse `file:status.json`
- Implement `metrics` action: Aggregate metrics from logs and history
- Write to `file:status.json` with proper JSON formatting
- Append to `file:logs/ralph.log` with timestamps
- Calculate metrics: total loops, success rate, average duration

**Integration Points**
- Read and write `file:status.json`
- Append to `file:logs/ralph.log`
- Use `update_status()` function from `file:ralph_loop.sh`
- Parse `file:progress.json` for real-time progress
- Aggregate data from `file:logs/` directory

### 9. Create Tool Registration System

**MCP Server Setup** (`file:sdk/src/server.ts`)
- Import `createSdkMcpServer` from Anthropic Agent SDK
- Register all 5 tools using the registration system
- Configure server name as `ralph` (tools will be `mcp__ralph__{tool_name}`)
- Set up error handling and logging middleware
- Export server instance for integration with SDK wrapper

**Tool Registration** (`file:sdk/src/tools/index.ts`)
- Export all tool implementations
- Create `registerRalphTools()` function
- Map tool names to implementations
- Validate tool schemas at registration time
- Provide tool discovery endpoint

**Configuration**
- Add environment variables for Ralph home directory (`RALPH_HOME`)
- Support custom paths for Ralph installation
- Configure logging levels and output destinations
- Set timeouts for shell command execution

### 10. Add Documentation

**Tool Documentation** (`file:sdk/README.md`)
- Document each tool's purpose and capabilities
- Provide usage examples for each action
- Include input/output schema documentation
- Add troubleshooting guide for common issues
- Document integration with existing Ralph bash scripts

**API Reference** (`file:sdk/docs/API.md`)
- Complete API reference for all 5 tools
- Document all actions and parameters
- Include response schemas and error codes
- Provide code examples in TypeScript
- Document MCP tool naming convention

**Integration Guide** (`file:sdk/docs/INTEGRATION.md`)
- Explain how tools integrate with Ralph's bash core
- Document shell command execution patterns
- Describe JSON communication protocol
- Provide debugging tips
- Include architecture diagrams

### 11. Write Tests

**Unit Tests** (files in `file:sdk/tests/tools/`)
- Test each tool's actions independently
- Mock shell command execution
- Validate input parameter validation
- Test error handling scenarios
- Verify JSON parsing and type safety
- Aim for 85%+ code coverage per tool

**Integration Tests** (`file:sdk/tests/integration/mcpServer.test.ts`)
- Test tool registration with MCP server
- Verify tool discovery and invocation
- Test end-to-end workflows with actual bash scripts
- Validate JSON communication between layers
- Test concurrent tool execution
- Verify error propagation from bash to SDK

**Test Utilities**
- Create mock shell executor for unit tests
- Provide fixture data for Ralph state files
- Create helper functions for test setup/teardown
- Mock file system operations for isolated testing

### 12. Integration with SDK Wrapper

**SDK Wrapper Integration** (depends on Phase 2.1 structure)
- Import and register Ralph MCP server in SDK wrapper
- Configure server lifecycle management
- Add Ralph tools to Claude Code's available tools
- Test tool invocation from Claude Code
- Verify tool names follow `mcp__ralph__{tool_name}` format

**Configuration Updates**
- Update `file:package.json` with SDK dependencies
- Add build scripts for TypeScript compilation
- Configure test runners (Jest or similar)
- Set up linting and formatting (ESLint, Prettier)

**Documentation Updates**
- Update `file:README.md` with Agent SDK integration section
- Add SDK tools to feature list
- Document installation steps for SDK components
- Update `file:CLAUDE.md` with SDK tool usage patterns

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Claude as Claude Code
    participant SDK as Agent SDK
    participant MCP as Ralph MCP Server
    participant Tools as Ralph Tools
    participant Shell as Shell Executor
    participant Bash as Ralph Bash Scripts
    participant Files as State Files

    Claude->>SDK: Request tool execution
    SDK->>MCP: mcp__ralph__rate_limit
    MCP->>Tools: RateLimitTool.check()
    Tools->>Shell: executeShellCommand()
    Shell->>Bash: source ralph_loop.sh; can_make_call
    Bash->>Files: Read .call_count
    Files-->>Bash: Current count
    Bash-->>Shell: Exit code + stdout
    Shell-->>Tools: Parsed result
    Tools->>Tools: Parse JSON output
    Tools-->>MCP: RateLimitToolOutput
    MCP-->>SDK: Tool result
    SDK-->>Claude: Response with data
```

## Tool Interaction Flow

```mermaid
graph TD
    A[Claude Code] -->|Calls tool| B[Agent SDK]
    B -->|Routes to| C[Ralph MCP Server]
    C -->|Dispatches| D{Tool Router}
    D -->|rate_limit| E[RateLimitTool]
    D -->|exit_detection| F[ExitDetectionTool]
    D -->|circuit_breaker| G[CircuitBreakerTool]
    D -->|task_planner| H[TaskPlannerTool]
    D -->|progress_reporter| I[ProgressReporterTool]
    E -->|Execute| J[Shell Executor]
    F -->|Execute| J
    G -->|Execute| J
    H -->|Execute| J
    I -->|Execute| J
    J -->|Run| K[Ralph Bash Scripts]
    K -->|Read/Write| L[State Files]
    L -->|Return| K
    K -->|Output| J
    J -->|Parse| E
    J -->|Parse| F
    J -->|Parse| G
    J -->|Parse| H
    J -->|Parse| I
```

## Testing Strategy

| Test Type | Coverage Target | Files |
|-----------|----------------|-------|
| Unit Tests | 85%+ per tool | `file:sdk/tests/tools/*.test.ts` |
| Integration Tests | Critical paths | `file:sdk/tests/integration/*.test.ts` |
| E2E Tests | Full workflows | Test with actual Ralph bash scripts |
| Type Safety | 100% | TypeScript strict mode enabled |

## Dependencies

- **Phase 2.1 (SDK POC)**: Must be complete before starting
- **Node.js**: v18+ for TypeScript and Agent SDK
- **TypeScript**: v5+ for type safety
- **Anthropic Agent SDK**: Latest version with MCP support
- **Existing Ralph**: v0.9.0 bash implementation
- **Test Framework**: Jest or Vitest for TypeScript testing

## Success Criteria

- All 5 custom tools implemented and functional
- Tools successfully registered with Agent SDK MCP server
- Tools callable from Claude Code with proper naming (`mcp__ralph__{tool_name}`)
- Unit tests pass with 85%+ coverage per tool
- Integration tests validate bash script communication
- Documentation complete with examples and API reference
- Tools integrate seamlessly with existing Ralph bash functionality
- No breaking changes to existing Ralph v0.9.0 behavior

---

Execution Information

Branch: main
Commit: 870181b