Orchestrata Ultimate / Specs / 062-cheetahclaws-tools-gap

062-cheetahclaws-tools-gap: CheetahClaws Tools Gap Analysis & Implementation

This specification defines the gap analysis and implementation plan for achieving 100% tool parity with Claude Code in the Ultimate Hybrid orchestrator. It identifies 14 missing tools and provides a phased implementation roadmap.

At a glance

Reading this spec

This spec is the umbrella gap analysis and plan for reaching 100% tool parity with Claude Code in the Ultimate Hybrid orchestrator. It states that the current completion rate is 65.9% (27 of 41 tools), identifies 14 missing tools, and lays out a phased roadmap over 12 weeks: critical tools (P0) first, then high (P1), medium (P2) and low (P3) priority. Each tool gets a governance mapping and an assignment to the agent that owns it, so multi-agent distribution is fully determined.

The five user stories cover interactive terminal sessions, multi-agent team coordination, remote tool execution, scheduled task execution and MCP resource management. Data models define the tool definition, REPL session, agent team and scheduled task schemas. The 125 requirement IDs (REQ-062-NNN) fall into core tool requirements, governance requirements and quality requirements, followed by error conditions, API contracts per tool and a table of metrics to emit. Examples of the core requirements are persistent-state PTY sessions, an ExitWorktreeTool that returns from a worktree to the main repository, and a ReadMcpResourceTool that reads MCP resource content by URI. ToolSearchTool.execute accepts a query, searches the tool registry and returns ranked results.

Constraints stated for all tools: PAM++ policy is enforced for every approval-required tool, and those tools are blocked until authorization is granted. REPLTool latency stays under 100 ms per command.

Each tool in the plan has its own spec, so the individual designs are in the specs for the REPL tool, git worktree tools, the LSP tool, the remote trigger tool, the schedule cron tool, task management tools, MCP resource tools and the tool search tool. The requirements traceability matrix lists every ID. The spec's own status line reads Complete and it tracks 2 files. No src/ symbol cites any of the 125 requirements, so measured trace coverage is 0.0%, and in tests/, 0 requirements are cited by a test-side @traces. All 125 requirements have no citing symbol; untraced means no @traces names the ID, and the behaviour may still exist in code that was never annotated.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

No src/ symbol cites a requirement of this spec.

Other tracked files

• specs/062-cheetahclaws-tools-gap/compliance-audit.md

Full spec text

Verbatim from specs/062-cheetahclaws-tools-gap/spec.md; headings are pushed down two levels.

SPEC-062: CheetahClaws Tools Gap Analysis & Implementation

Metadata

• Spec ID: 062-cheetahclaws-tools-gap
• Title: CheetahClaws Tools Gap Analysis & Implementation Plan
• Author: Mohamed
• Status: Complete
• Created: 2026-04-08
• Last Updated: 2026-04-09
• Priority: P0
• Version: 1.0.0
• Extends: SPEC-001 Ultimate Architecture

Overview

What

This specification defines the gap analysis and implementation plan for achieving 100% tool parity with Claude Code in the Ultimate Hybrid orchestrator. It identifies 14 missing tools and provides a phased implementation roadmap.

Why

Tool parity with Claude Code is essential for maintaining feature equivalence and ensuring seamless user experience. The current 65.9% completion rate (27/41 tools) leaves significant functionality gaps that must be addressed.

How

The implementation follows a phased approach over 12 weeks, prioritizing critical tools (P0), then high-priority (P1), medium-priority (P2), and low-priority (P3) tools. Each tool includes governance mapping and multi-agent distribution assignments.

User Scenarios

US-001: Interactive Terminal Session

• As a developer
• I want to execute interactive terminal sessions with persistent state
• So that I can run REPL-based workflows, debug applications, and interact with CLI tools that require TTY
• Acceptance Criteria:
  • PTY session maintains persistent state across commands
  • Multi-line input is properly handled
  • Ctrl+C and Ctrl+D are correctly processed
  • Output streams in real-time
  • Session can be resumed by ID

REQ-062-001: The system SHALL execute interactive terminal sessions with persistent state. The PTY session SHALL maintain persistent state across commands, multi-line input SHALL be properly handled, Ctrl+C and Ctrl+D SHALL be correctly processed, output SHALL stream in real-time, and a session SHALL be resumable by ID.

US-002: Multi-Agent Team Coordination

• As a project manager
• I want to create and manage teams of specialized agents
• So that I can coordinate complex workflows across different agent capabilities
• Acceptance Criteria:
  • Teams can be created with multiple agents
  • Agent coordination is configurable
  • Teams can be deleted with proper cleanup
  • Agent assignments persist across sessions

REQ-062-002: The system SHALL create and manage teams of specialized agents. Teams SHALL be creatable with multiple agents, agent coordination SHALL be configurable, teams SHALL be deletable with proper cleanup, and agent assignments SHALL persist across sessions.

US-003: Remote Tool Execution

• As a DevOps engineer
• I want to trigger tool execution on remote systems via SSH
• So that I can manage infrastructure and run commands across distributed systems
• Acceptance Criteria:
  • SSH connections are established securely
  • Tools can be executed on remote hosts
  • Credentials are handled securely
  • Results are returned to the local session

REQ-062-003: The system SHALL trigger tool execution on remote systems via SSH. SSH connections SHALL be established securely, tools SHALL be executable on remote hosts, credentials SHALL be handled securely, and results SHALL be returned to the local session.

US-004: Scheduled Task Execution

• As a system administrator
• I want to schedule tool execution via cron expressions
• So that I can automate periodic maintenance and monitoring tasks
• Acceptance Criteria:
  • Cron expressions are parsed correctly
  • Tasks execute at scheduled times
  • Scheduling persists across restarts
  • Missed executions are handled appropriately

REQ-062-004: The system SHALL schedule tool execution via cron expressions. Cron expressions SHALL be parsed correctly, tasks SHALL execute at their scheduled times, scheduling SHALL persist across restarts, and missed executions SHALL be handled.

US-005: MCP Resource Management

• As a integration developer
• I want to list and read MCP server resources
• So that I can integrate with Model Context Protocol servers
• Acceptance Criteria:
  • MCP resources are discoverable
  • Resource content is retrievable
  • Authentication is handled properly
  • Server connection errors are gracefully managed

REQ-062-005: The system SHALL list and read MCP server resources. MCP resources SHALL be discoverable, resource content SHALL be retrievable, authentication SHALL be handled, and MCP server connection errors SHALL be managed gracefully.

Terminology

Data Models

Tool Definition Schema

{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "Unique tool identifier"},
    "description": {"type": "string", "description": "Human-readable description"},
    "category": {"type": "string", "enum": ["file", "shell", "search", "web", "task", "memory", "planning", "agent", "config", "mcp", "utility"]},
    "parameters": {"type": "object", "description": "JSON Schema for tool parameters"},
    "priority": {"type": "string", "enum": ["P0", "P1", "P2", "P3"]},
    "requires_approval": {"type": "boolean"},
    "governance_article": {"type": "string", "description": "PAM++ article reference"},
    "estimated_hours": {"type": "integer", "minimum": 1},
    "dependencies": {"type": "array", "items": {"type": "string"}}
  },
  "required": ["name", "description", "category", "priority"]
}

REQ-062-006: Every tool definition SHALL conform to the Tool Definition Schema above: name, description, category, and priority SHALL be required; category SHALL be one of file, shell, search, web, task, memory, planning, agent, config, mcp, utility; priority SHALL be one of P0, P1, P2, P3; and estimated_hours SHALL be an integer of at least 1.

REPL Session Schema

{
  "type": "object",
  "properties": {
    "session_id": {"type": "string", "description": "Unique session identifier"},
    "created_at": {"type": "string", "format": "date-time"},
    "command_history": {"type": "array", "items": {"type": "string"}},
    "environment": {"type": "object"},
    "working_directory": {"type": "string"}
  },
  "required": ["session_id", "created_at"]
}

REQ-062-007: Every REPL session record SHALL conform to the REPL Session Schema above, carrying session_id, created_at, command_history, environment, and working_directory, with session_id and created_at required and created_at in date-time format.

Agent Team Schema

{
  "type": "object",
  "properties": {
    "team_id": {"type": "string", "description": "Unique team identifier"},
    "name": {"type": "string", "description": "Team name"},
    "agents": {"type": "array", "items": {"type": "string"}},
    "coordination_mode": {"type": "string", "enum": ["sequential", "parallel", "hierarchical"]},
    "created_at": {"type": "string", "format": "date-time"},
    "status": {"type": "string", "enum": ["active", "paused", "terminated"]}
  },
  "required": ["team_id", "name", "agents", "coordination_mode"]
}

REQ-062-008: Every agent team record SHALL conform to the Agent Team Schema above: team_id, name, agents, and coordination_mode SHALL be required; coordination_mode SHALL be one of sequential, parallel, hierarchical; and status SHALL be one of active, paused, terminated.

Scheduled Task Schema

{
  "type": "object",
  "properties": {
    "task_id": {"type": "string", "description": "Unique task identifier"},
    "schedule": {"type": "string", "description": "Cron expression"},
    "tool_name": {"type": "string", "description": "Tool to execute"},
    "arguments": {"type": "object"},
    "enabled": {"type": "boolean"},
    "last_run": {"type": "string", "format": "date-time"},
    "next_run": {"type": "string", "format": "date-time"}
  },
  "required": ["task_id", "schedule", "tool_name"]
}

REQ-062-009: Every scheduled task record SHALL conform to the Scheduled Task Schema above, carrying task_id, schedule (a cron expression), tool_name, arguments, enabled, last_run, and next_run, with task_id, schedule, and tool_name required and last_run/next_run in date-time format.

Functional Requirements

Core Tool Requirements

FR-001: REQ-062-010: The system MUST implement REPLTool with PTY session management supporting persistent command sessions with session_id tracking.

FR-002: REQ-062-011: The system MUST implement EnterWorktreeTool to enter git worktree directories with automatic branch detection.

FR-003: REQ-062-012: The system MUST implement ExitWorktreeTool to return to the main repository from a worktree context.

FR-004: REQ-062-013: The system MUST implement enhanced LSPTool with automatic language detection and support for complete, hover, diagnostics, goto, and references actions.

FR-005: REQ-062-014: The system MUST implement PowerShellTool for Windows PowerShell command execution with proper timeout handling.

FR-006: REQ-062-015: The system MUST implement RemoteTriggerTool for secure SSH-based remote tool execution with credential management.

FR-007: REQ-062-016: The system MUST implement ScheduleCronTool for cron-based task scheduling with expression validation.

FR-008: REQ-062-017: The system MUST implement TaskStopTool to terminate running tasks with proper resource cleanup.

FR-009: REQ-062-018: The system MUST implement TaskOutputTool to retrieve stdout/stderr from running or completed tasks.

FR-010: REQ-062-019: The system MUST implement TeamCreateTool for creating multi-agent teams with configurable coordination modes.

FR-011: REQ-062-020: The system MUST implement TeamDeleteTool for deleting agent teams with graceful agent termination.

FR-012: REQ-062-021: The system MUST implement ToolSearchTool for searching the tool registry by capability and metadata.

FR-013: REQ-062-022: The system MUST implement ListMcpResourcesTool for discovering MCP server resources.

FR-014: REQ-062-023: The system MUST implement ReadMcpResourceTool for retrieving MCP resource content by URI.

FR-015: REQ-062-024: The system MUST implement McpAuthTool for configuring and managing MCP server authentication.

Governance Requirements

FR-016: REQ-062-025: All tools requiring approval MUST be mapped to PAM++ governance articles before implementation.

FR-017: REQ-062-026: All tools MUST have agent assignment configurations for multi-agent distribution.

FR-018: REQ-062-027: The system MUST maintain a tool governance map with timeout values and approval requirements.

Quality Requirements

FR-019: REQ-062-028: Each implemented tool MUST have minimum 20 unit test cases with 90% code coverage.

FR-020: REQ-062-029: All tools MUST pass integration tests with real system calls.

FR-021: REQ-062-030: Tool implementations MUST follow the base tool interface defined in SPEC-001.

Error Conditions

Each row below is normative: when the stated condition occurs, the system SHALL perform the stated handling.

API Contracts

REPLTool

REQ-062-059: REPLTool.execute SHALL accept command: str, an optional session_id: str, and timeout: int defaulting to 60, SHALL execute the command in an interactive terminal session, and SHALL return a ToolResult carrying stdout, stderr, and exit_code.

class REPLTool(BaseTool):
    name = "REPLTool"
    
    async def execute(
        command: str,
        session_id: Optional[str] = None,
        timeout: int = 60
    ) -> ToolResult:
        """
        Execute command in interactive terminal session.
        
        Args:
            command: Shell command to execute
            session_id: Optional session ID for persistence
            timeout: Command timeout in seconds
            
        Returns:
            ToolResult with stdout, stderr, exit_code
        """

EnterWorktreeTool

REQ-062-060: EnterWorktreeTool.execute SHALL accept worktree_path: str and an optional branch: str, SHALL enter the named git worktree directory, and SHALL return a ToolResult carrying the new working directory.

class EnterWorktreeTool(BaseTool):
    name = "EnterWorktreeTool"
    
    async def execute(
        worktree_path: str,
        branch: Optional[str] = None
    ) -> ToolResult:
        """
        Enter a git worktree directory.
        
        Args:
            worktree_path: Path to worktree directory
            branch: Optional branch name
            
        Returns:
            ToolResult with new working directory
        """

ExitWorktreeTool

REQ-062-061: ExitWorktreeTool.execute SHALL take no arguments, SHALL exit the current worktree back to the main repository, and SHALL return a ToolResult carrying the main repository path.

class ExitWorktreeTool(BaseTool):
    name = "ExitWorktreeTool"
    
    async def execute() -> ToolResult:
        """
        Exit current worktree to main repository.
        
        Returns:
            ToolResult with main repo path
        """

LSPTool

REQ-062-062: LSPTool.execute SHALL accept action restricted to complete, hover, diagnostics, goto, or references, file_path: str, and optional line: int and column: int, SHALL execute the named LSP action on the file, and SHALL return a ToolResult carrying action-specific data.

class LSPTool(BaseTool):
    name = "LSPTool"
    
    async def execute(
        action: Literal["complete", "hover", "diagnostics", "goto", "references"],
        file_path: str,
        line: Optional[int] = None,
        column: Optional[int] = None
    ) -> ToolResult:
        """
        Execute LSP action on file.
        
        Returns:
            ToolResult with action-specific data
        """

RemoteTriggerTool

REQ-062-063: RemoteTriggerTool.execute SHALL accept tool_name: str, args: dict, target: str, an optional credentials: dict, and timeout: int defaulting to 60, SHALL trigger the named tool's execution on the remote system, and SHALL return a ToolResult carrying the remote execution output.

class RemoteTriggerTool(BaseTool):
    name = "RemoteTriggerTool"
    
    async def execute(
        tool_name: str,
        args: dict,
        target: str,
        credentials: Optional[dict] = None,
        timeout: int = 60
    ) -> ToolResult:
        """
        Trigger tool execution on remote system.
        
        Returns:
            ToolResult with remote execution output
        """

ScheduleCronTool

REQ-062-064: ScheduleCronTool.execute SHALL accept schedule: str, tool: str, an optional args: dict, and enabled: bool defaulting to true, SHALL schedule the tool's execution via cron, and SHALL return a ToolResult carrying the task_id and a schedule confirmation.

class ScheduleCronTool(BaseTool):
    name = "ScheduleCronTool"
    
    async def execute(
        schedule: str,
        tool: str,
        args: Optional[dict] = None,
        enabled: bool = True
    ) -> ToolResult:
        """
        Schedule tool execution via cron.
        
        Returns:
            ToolResult with task_id and schedule confirmation
        """

TeamCreateTool

REQ-062-065: TeamCreateTool.execute SHALL accept name: str, agents: List[str], and an optional coordination: dict, SHALL create the multi-agent team, and SHALL return a ToolResult carrying the team_id and the team configuration.

class TeamCreateTool(BaseTool):
    name = "TeamCreateTool"
    
    async def execute(
        name: str,
        agents: List[str],
        coordination: Optional[dict] = None
    ) -> ToolResult:
        """
        Create multi-agent team.
        
        Returns:
            ToolResult with team_id and configuration
        """

ListMcpResourcesTool

REQ-062-066: ListMcpResourcesTool.execute SHALL accept server: str, SHALL list that MCP server's resources, and SHALL return a ToolResult carrying the resource list.

class ListMcpResourcesTool(BaseTool):
    name = "ListMcpResourcesTool"
    
    async def execute(server: str) -> ToolResult:
        """
        List MCP server resources.
        
        Returns:
            ToolResult with resource list
        """

Non-Functional Requirements

Performance

• REQ-062-101: REPLTool latency SHALL be <100ms per command execution
• REQ-062-102: LSP diagnostics SHALL complete in <500ms for files under 10,000 lines
• REQ-062-103: MCP resource listing SHALL have a <200ms response time
• REQ-062-104: Tool search SHALL complete in <100ms for queries across 100+ tools

Reliability

• REQ-062-105: Tool availability SHALL be 99.9% uptime for implemented tools
• REQ-062-106: The system SHALL degrade gracefully when optional dependencies are unavailable
• REQ-062-107: The system SHALL retry automatically with exponential backoff for transient failures
• REQ-062-108: Sessions SHALL persist across orchestrator restarts

Security

• REQ-062-109: SSH credentials SHALL be encrypted at rest using AES-256
• REQ-062-110: MCP authentication tokens SHALL be stored in a secure vault
• REQ-062-111: REPLTool SHALL prevent command injection
• REQ-062-112: PAM++ policy SHALL be enforced for all approval-required tools

Compatibility

• REQ-062-113: Linux SHALL support all tools
• REQ-062-114: macOS SHALL support all tools
• REQ-062-115: Windows SHALL require PowerShellTool, with Unix tools provided via WSL

Technical Design

Architecture Overview

The tool gap implementation follows a modular architecture where each tool extends the BaseTool class and implements the ToolResult interface. Tools are registered in the ToolRegistry with governance metadata.

REQ-062-067: Each tool SHALL extend the BaseTool class and implement the ToolResult interface, and SHALL be registered in the ToolRegistry with governance metadata.

Component Structure

src/
├── tools/
│   ├── repl/
│   │   ├── __init__.py
│   │   ├── repl_tool.py
│   │   └── session_manager.py
│   ├── worktree/
│   │   ├── __init__.py
│   │   ├── enter_worktree.py
│   │   └── exit_worktree.py
│   ├── lsp/
│   │   ├── __init__.py
│   │   ├── lsp_tool.py
│   │   └── language_detector.py
│   ├── powershell/
│   │   ├── __init__.py
│   │   └── powershell_tool.py
│   ├── remote/
│   │   ├── __init__.py
│   │   ├── remote_trigger.py
│   │   └── ssh_manager.py
│   ├── scheduling/
│   │   ├── __init__.py
│   │   └── cron_scheduler.py
│   ├── task/
│   │   ├── __init__.py
│   │   ├── task_stop.py
│   │   └── task_output.py
│   ├── team/
│   │   ├── __init__.py
│   │   ├── team_create.py
│   │   └── team_delete.py
│   └── mcp/
│       ├── __init__.py
│       ├── list_resources.py
│       ├── read_resource.py
│       └── mcp_auth.py
└── registry/
    └── tool_registry.py

Session Management

REPLTool uses a session manager that maintains PTY instances indexed by session_id. Sessions persist in memory during runtime and can be serialized to disk for cross-session continuity.

REQ-062-068: REPLTool SHALL use a session manager that maintains PTY instances indexed by session_id. Sessions SHALL persist in memory during runtime and SHALL be serializable to disk for cross-session continuity.

Worktree State

Worktree tools maintain state in the orchestrator context, tracking current working directory and repository root for proper navigation.

REQ-062-069: The worktree tools SHALL maintain state in the orchestrator context, tracking the current working directory and the repository root.

Examples

Example 1: REPL Interactive Session

{
  "tool": "REPLTool",
  "input": {
    "command": "python3 -i",
    "session_id": "repl-session-001",
    "timeout": 300
  },
  "output": {
    "success": true,
    "stdout": "Python 3.14.0...",
    "session_persisted": true
  }
}

Example 2: Team Creation

{
  "tool": "TeamCreateTool",
  "input": {
    "name": "deployment-team",
    "agents": ["U:Cd", "U:Ar", "U:Qa"],
    "coordination": {
      "mode": "sequential",
      "on_failure": "rollback"
    }
  },
  "output": {
    "team_id": "team-042",
    "status": "active"
  }
}

Example 3: Remote Trigger

{
  "tool": "RemoteTriggerTool",
  "input": {
    "tool_name": "BashTool",
    "args": {"command": "docker ps"},
    "target": "prod-server-01",
    "credentials": {"use_agent": true}
  },
  "output": {
    "success": true,
    "result": "container-id-1\ncontainer-id-2"
  }
}

Example 4: Cron Scheduling

{
  "tool": "ScheduleCronTool",
  "input": {
    "schedule": "0 0 * * *",
    "tool": "BashTool",
    "args": {"command": "/opt/backup.sh"},
    "enabled": true
  },
  "output": {
    "task_id": "cron-task-042",
    "next_run": "2026-04-10T00:00:00Z"
  }
}

Example 5: MCP Resource Listing

{
  "tool": "ListMcpResourcesTool",
  "input": {
    "server": "filesystem"
  },
  "output": {
    "success": true,
    "resources": [
      {"uri": "filesystem:///etc/hosts", "type": "file"},
      {"uri": "filesystem:///var/log", "type": "directory"}
    ]
  }
}

Security

Authentication

• REQ-062-116: SSH Authentication — The system SHALL support key-based (RSA, Ed25519) and agent-forward authentication. Private keys SHALL never be transmitted; only the agent socket SHALL be used.
• REQ-062-117: MCP Authentication — The system SHALL support OAuth2 and API key-based authentication. Credentials SHALL be stored in an encrypted vault.
• REQ-062-118: PowerShell Authentication — The system SHALL integrate with Windows credential management.

Authorization

• REQ-062-119: All tools SHALL enforce PAM++ governance policies
• REQ-062-120: Approval-required tools SHALL be blocked until authorization is granted
• REQ-062-121: Tool access SHALL be role-based (read, write, execute)

Input Validation

• REQ-062-122: Command injection SHALL be prevented via allowlist validation
• REQ-062-123: Path traversal SHALL be prevented via canonical path checking
• REQ-062-124: Cron expressions SHALL be validated before scheduling
• REQ-062-125: All tool parameters SHALL be validated against their JSON schema

Audit Logging

• REQ-062-126: All tool executions SHALL be logged with timestamp, user, tool, arguments, result
• REQ-062-127: Governance decisions (approval/denial) SHALL be logged
• REQ-062-128: Remote execution SHALL be logged with source and target
• REQ-062-129: Audit logs SHALL be retained for 90 days minimum

Governance

Tool Governance Mapping

REQ-062-070: The tool governance map SHALL carry, for every tool, the approval requirement, PAM++ article, and timeout given in the table below. RemoteTriggerTool (Article X), ScheduleCronTool (Article V), TeamCreateTool and TeamDeleteTool (Article VIII), ReadMcpResourceTool (Article III), and McpAuthTool (Article IV) SHALL require approval; the remaining tools SHALL NOT.

Agent Assignment

REQ-062-071: Every tool SHALL be assigned to the agent given in the table below, so that multi-agent distribution is fully determined.

Integration Points

BaseTool Interface

All tools extend the BaseTool abstract class implementing:

• name property (tool identifier)
• description property (human-readable description)
• execute(**kwargs) method (async tool execution)
• validate() method (parameter validation)

REQ-062-072: All tools SHALL extend the BaseTool abstract class and implement the name property (tool identifier), the description property (human-readable description), the async execute(**kwargs) method, and the validate() method (parameter validation).

ToolRegistry Integration

Tools registered in ToolRegistry with metadata:

registry.register_tool({
    "name": "REPLTool",
    "class": REPLTool,
    "governance": {"requires_approval": False},
    "agent_assignments": ["U:Cd"],
    "dependencies": ["pty", "asyncio"]
})

REQ-062-073: Every tool SHALL be registered in the ToolRegistry with metadata carrying its name, its implementing class, its governance block (including requires_approval), its agent_assignments, and its dependencies.

Orchestrator Context

Tools receive OrchestratorContext providing:

• Current working directory tracking
• Git repository state
• Agent assignments
• PAM++ policy lookup
• Session management

REQ-062-074: Every tool SHALL receive an OrchestratorContext providing current-working-directory tracking, git repository state, agent assignments, PAM++ policy lookup, and session management.

Event System

Tools emit events for integration:

• tool.executed - Tool execution started/completed
• tool.error - Tool execution error
• session.created - New session created
• team.created - New team created
• task.scheduled - Task scheduled successfully

REQ-062-075: Tools SHALL emit the integration events tool.executed (execution started/completed), tool.error (execution error), session.created, team.created, and task.scheduled.

Implementation Inventory

Completed Tools (27/41) ✅

Missing Tools (14/41) ❌

Priority 0 (P0) - Critical

Priority 1 (P1) - High

Priority 2 (P2) - Medium

Priority 3 (P3) - Low

Tool Specifications

3.1 REPLTool (P0)

class REPLTool(BaseTool):
    """Interactive terminal REPL session."""
    
    name = "REPLTool"
    description = "Interactive terminal REPL session"
    
    parameters = {
        "type": "object",
        "properties": {
            "command": {"type": "string", "description": "Command to execute"},
            "session_id": {"type": "string", "description": "Session ID for persistence"},
            "timeout": {"type": "integer", "default": 60}
        },
        "required": ["command"]
    }
    
    async def execute(
        self,
        command: str,
        session_id: str = None,
        timeout: int = 60
    ) -> ToolResult:
        # PTY session management
        # Multi-line input handling
        # Output streaming
        # Ctrl+C, Ctrl+D handling

3.2 Worktree Tools (P0)

class EnterWorktreeTool(BaseTool):
    """Enter a git worktree directory."""
    
    name = "EnterWorktreeTool"
    description = "Enter a git worktree directory"
    
    parameters = {
        "type": "object",
        "properties": {
            "worktree_path": {"type": "string"},
            "branch": {"type": "string", "description": "Branch name"}
        },
        "required": ["worktree_path"]
    }


class ExitWorktreeTool(BaseTool):
    """Exit current worktree back to main repo."""
    
    name = "ExitWorktreeTool"
    description = "Exit worktree to main repository"

3.3 LSPTool Enhanced (P0)

class LSPTool(BaseTool):
    """Language Server Protocol integration."""
    
    name = "LSPTool"
    description = "LSP integration for diagnostics, completion, etc."
    
    parameters = {
        "type": "object",
        "properties": {
            "action": {
                "type": "string",
                "enum": ["complete", "hover", "diagnostics", "goto", "references"]
            },
            "file_path": {"type": "string"},
            "line": {"type": "integer"},
            "column": {"type": "integer"}
        },
        "required": ["action", "file_path"]
    }

3.4 PowerShellTool (P1)

REQ-062-076: PowerShellTool SHALL be named PowerShellTool, SHALL be described as "Execute PowerShell commands on Windows", and SHALL accept a required command: string parameter and a timeout: integer parameter defaulting to 60.

class PowerShellTool(BaseTool):
    """Execute PowerShell commands."""
    
    name = "PowerShellTool"
    description = "Execute PowerShell commands on Windows"
    
    parameters = {
        "type": "object",
        "properties": {
            "command": {"type": "string"},
            "timeout": {"type": "integer", "default": 60}
        },
        "required": ["command"]
    }

3.5 RemoteTriggerTool (P1)

class RemoteTriggerTool(BaseTool):
    """Trigger tools on remote systems via SSH."""
    
    name = "RemoteTriggerTool"
    description = "Execute tools on remote systems"
    
    parameters = {
        "type": "object",
        "properties": {
            "tool_name": {"type": "string"},
            "args": {"type": "object"},
            "target": {"type": "string", "description": "SSH host"},
            "credentials": {"type": "object"}
        },
        "required": ["tool_name", "target"]
    }

3.6 ScheduleCronTool (P1)

class ScheduleCronTool(BaseTool):
    """Schedule tool execution via cron."""
    
    name = "ScheduleCronTool"
    description = "Schedule tool execution"
    
    parameters = {
        "type": "object",
        "properties": {
            "schedule": {"type": "string", "description": "Cron expression"},
            "tool": {"type": "string"},
            "args": {"type": "object"}
        },
        "required": ["schedule", "tool"]
    }

3.7 Task Management Tools (P2)

REQ-062-077: TaskStopTool.execute SHALL accept task_id: str, SHALL locate the task, SHALL send it SIGTERM followed by SIGKILL, SHALL clean up its resources, and SHALL return a ToolResult.

REQ-062-078: TaskOutputTool.execute SHALL accept task_id: str, SHALL retrieve that task's stdout and stderr, and SHALL return the formatted output in a ToolResult.

class TaskStopTool(BaseTool):
    """Stop a running task."""
    
    name = "TaskStopTool"
    description = "Stop a running task"
    
    async def execute(self, task_id: str) -> ToolResult:
        # Find task
        # Send SIGTERM/SIGKILL
        # Cleanup resources


class TaskOutputTool(BaseTool):
    """Get task output."""
    
    name = "TaskOutputTool"
    description = "Retrieve task output"
    
    async def execute(self, task_id: str) -> ToolResult:
        # Get stdout/stderr
        # Format output

3.8 Team Tools (P2)

REQ-062-079: TeamDeleteTool.execute SHALL accept team_id: str, SHALL stop all of that team's agents, SHALL clean up their resources, SHALL delete the team record, and SHALL return a ToolResult.

class TeamCreateTool(BaseTool):
    """Create a team of agents."""
    
    name = "TeamCreateTool"
    description = "Create multi-agent team"
    
    parameters = {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "agents": {"type": "array", "items": {"type": "string"}},
            "coordination": {"type": "object"}
        },
        "required": ["name", "agents"]
    }


class TeamDeleteTool(BaseTool):
    """Delete an agent team."""
    
    name = "TeamDeleteTool"
    description = "Delete agent team"
    
    async def execute(self, team_id: str) -> ToolResult:
        # Stop all agents
        # Cleanup resources
        # Delete team record

3.9 MCP Resource Tools (P3)

REQ-062-080: ReadMcpResourceTool.execute SHALL accept resource_uri: str, SHALL parse that URI, SHALL fetch the resource content, and SHALL return the data in a ToolResult.

REQ-062-081: McpAuthTool.execute SHALL accept server: str and credentials: dict, SHALL store those credentials securely, SHALL test the connection, and SHALL return a ToolResult.

class ListMcpResourcesTool(BaseTool):
    """List MCP server resources."""
    
    name = "ListMcpResourcesTool"
    description = "List available MCP resources"
    
    async def execute(self, server: str) -> ToolResult:
        # Connect to MCP server
        # List resources
        # Return formatted


class ReadMcpResourceTool(BaseTool):
    """Read MCP resource content."""
    
    name = "ReadMcpResourceTool"
    description = "Read MCP resource"
    
    async def execute(self, resource_uri: str) -> ToolResult:
        # Parse URI
        # Fetch content
        # Return data


class McpAuthTool(BaseTool):
    """Handle MCP authentication."""
    
    name = "McpAuthTool"
    description = "Configure MCP authentication"
    
    async def execute(self, server: str, credentials: dict) -> ToolResult:
        # Store credentials securely
        # Test connection

3.10 ToolSearchTool (P3)

REQ-062-082: ToolSearchTool.execute SHALL accept query: str, SHALL search the tool registry, SHALL rank the matches by relevance, and SHALL return the ranked results in a ToolResult.

class ToolSearchTool(BaseTool):
    """Search for tools by capability."""
    
    name = "ToolSearchTool"
    description = "Search tool registry"
    
    async def execute(self, query: str) -> ToolResult:
        # Search tool registry
        # Rank by relevance
        # Return results

Implementation Roadmap

Phase 1: Core Missing Tools (Week 1-4)

Phase 2: Advanced Tools (Week 5-8)

Phase 3: Team & MCP Tools (Week 9-10)

Phase 4: Polish (Week 11-12)

Dependencies

System Dependencies

• Python 3.14t
• Git (for worktree tools)
• PTY support (for REPLTool)
• SSH client (for RemoteTriggerTool)
• Cron daemon (for ScheduleCronTool)
• PowerShell (for PowerShellTool - Windows)

Python Dependencies

• pyte - Terminal emulation
• python-pty - PTY handling
• croniter - Cron parsing
• paramiko - SSH client

Testing Requirements

Unit Tests

• Each tool: minimum 20 test cases
• Mock external dependencies
• Error handling coverage: 100%

REQ-062-083: Each tool SHALL have a minimum of 20 unit test cases and SHALL reach 100% error-handling coverage.

Integration Tests

• Real system calls (git, SSH, cron)
• Cross-platform testing (Linux, Windows)
• Performance benchmarks

REQ-062-084: Integration tests SHALL exercise real system calls (git, SSH, cron), SHALL run cross-platform on Linux and Windows, and SHALL include performance benchmarks.

E2E Tests

• Complete tool workflows
• Governance integration
• Multi-agent scenarios

REQ-062-085: End-to-end tests SHALL cover complete tool workflows, governance integration, and multi-agent scenarios.

Risk Assessment

Success Criteria

1. REQ-062-086: Completion — All 14 missing tools SHALL be implemented.
2. REQ-062-087: Parity — Tool parity with Claude Code SHALL reach 41/41 tools = 100%.
3. REQ-062-088: Quality — All tools SHALL pass code review.
4. REQ-062-089: Testing — Test coverage SHALL be ≥90%.
5. REQ-062-090: Documentation — All tools SHALL be documented with examples.
6. REQ-062-091: Governance — All tools SHALL be mapped to PAM++ policies.

Open Items

Observability

Logging Requirements

REQ-062-130: The system SHALL satisfy every component-logging criterion enumerated below.

1. Component Logging
   • Log all major operations with appropriate log levels
   • Include correlation IDs for request tracing
   • Log performance metrics for critical operations
   • Log errors with full context for debugging

Metrics Requirements

REQ-062-131: The system SHALL emit every performance metric enumerated below.

1. Performance Metrics
   • Operation duration histograms
   • Request/error rate counters
   • Resource utilization gauges
   • Business metrics relevant to domain

Tracing Requirements

REQ-062-132: The system SHALL satisfy every distributed-tracing criterion enumerated below.

1. Distributed Tracing
   • Trace propagation across component boundaries
   • Span attributes for domain-specific context
   • Trace sampling based on operational needs

Alerting Requirements

REQ-062-133: The system SHALL raise every critical alert enumerated below.

1. Critical Alerts
   • Error rate spikes
   • Performance degradation
   • Resource exhaustion
   • Business metric anomalies

Dashboard Requirements

REQ-062-134: The system SHALL provide an operational dashboard carrying every element enumerated below.

1. Operational Dashboard
   • Real-time system health
   • Performance trends
   • Error analysis
   • Resource monitoring

Revision History

End of SPEC-062: CheetahClaws Tools Gap

Related

• RTM page for 062-cheetahclaws-tools-gap
• All specs
• RTM overview
• Gates