---
actual_hours: null
assignees: []
created_at: '2025-01-25T10:00:00.000000'
dependencies: []
description: Replace the HTTP-based hook service implementation with a lightweight JSON-RPC approach to eliminate port exhaustion and reduce resource usage
due_date: null
estimated_hours: 16
id: TSK-0046
labels: [architecture, performance, refactoring]
metadata:
  created_by: claude-mpm
  ticket_type: task
parent: null
priority: high
status: open
tags:
- task
- hooks
- json-rpc
- refactoring
title: 'Replace HTTP-based Hook Service with JSON-RPC Implementation'
updated_at: '2025-01-25T10:00:00.000000'
---

# TSK-0046: Replace HTTP-based Hook Service with JSON-RPC Implementation

## Problem Statement
The current hook service implementation spawns a separate HTTP server (Flask) for each claude-mpm instance, leading to:
- Port exhaustion in the 8080-8099 range
- Resource waste from multiple Flask server processes
- Complex service lifecycle management
- Unnecessary network overhead for local hook execution

## Proposed Solution
Replace the HTTP-based hook service with a lightweight JSON-RPC implementation that:
1. Executes hooks as direct subprocess calls
2. Communicates via stdin/stdout using JSON-RPC format
3. Eliminates the need for persistent HTTP servers
4. Shares hook implementations across all processes

## Implementation Plan

### Phase 1: Design JSON-RPC Protocol
- Define JSON-RPC request/response format for hooks
- Specify error handling and timeout mechanisms
- Document hook execution lifecycle

### Phase 2: Implement Core JSON-RPC Infrastructure
- Create `JSONRPCHookExecutor` class
- Implement request/response serialization
- Add subprocess management with proper error handling

### Phase 3: Create Hook Runner Script
- Develop standalone hook runner that accepts JSON-RPC requests
- Support all existing hook types (submit, pre/post delegation, etc.)
- Implement hook discovery and loading mechanism

### Phase 4: Update Hook Client
- Replace HTTP client with JSON-RPC subprocess calls
- Maintain backward compatibility with existing hook interface
- Add retry logic and timeout handling

### Phase 5: Migration and Cleanup
- Update all orchestrators to use new hook system
- Remove Flask-based hook service code
- Update tests and documentation
- Clean up port management code

## Technical Details

### JSON-RPC Format Example
```json
// Request
{
  "jsonrpc": "2.0",
  "method": "execute_hook",
  "params": {
    "hook_type": "submit",
    "hook_name": "validation_hook",
    "context": {
      "data": {"prompt": "test"},
      "metadata": {"session_id": "123"}
    }
  },
  "id": "1"
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "success": true,
    "data": {"prompt": "test"},
    "modified": false,
    "metadata": {"validated": true}
  },
  "id": "1"
}
```

### Benefits
- No port management needed
- Reduced resource usage
- Simpler deployment
- Better isolation between processes
- Easier testing and debugging

## Acceptance Criteria
- [ ] All existing hooks work with new JSON-RPC system
- [ ] No HTTP servers spawned for hook execution
- [ ] Performance equal or better than HTTP-based system
- [ ] All tests pass with new implementation
- [ ] Documentation updated with new architecture

## Dependencies
- None

## Related Issues
- Port exhaustion issues reported by users
- Complex hook service lifecycle management

## Notes
- Consider using existing JSON-RPC libraries for Python
- Ensure Windows compatibility for subprocess communication
- Maintain hook execution order and priority