emdash-core 0.1.7__py3-none-any.whl → 0.1.33__py3-none-any.whl

emdash_core/agent/tools/modes.py

@@ -1,10 +1,9 @@
 """Agent mode management tools.
 
-Provides tools for switching between different agent modes
-(exploration, planning, coding, etc).
+Provides tools for entering and exiting modes, following
+Claude Code's approach of explicit mode transitions.
 """
 
-from dataclasses import dataclass
 from enum import Enum
 from typing import Optional
 
@@ -13,26 +12,26 @@ from .base import BaseTool, ToolResult, ToolCategory
 
 class AgentMode(Enum):
     """Available agent modes."""
+    PLAN = "plan"
+    CODE = "code"
 
-    EXPLORATION = "exploration"
-    PLANNING = "planning"
-    CODING = "coding"
-    REVIEW = "review"
-    DEBUG = "debug"
+
+# Modes that can be entered via enter_mode tool
+SUPPORTED_MODES = ["plan"]  # Extensible list
 
 
-@dataclass
 class ModeState:
     """Singleton state for agent mode."""
 
-    current_mode: AgentMode = AgentMode.EXPLORATION
-    mode_context: dict = None
-
     _instance: Optional["ModeState"] = None
 
-    def __post_init__(self):
-        if self.mode_context is None:
-            self.mode_context = {}
+    def __init__(self):
+        self.current_mode: AgentMode = AgentMode.CODE
+        self.plan_content: Optional[str] = None  # Stores the current plan
+        self.plan_submitted: bool = False  # Track if exit_plan was called this cycle
+        self.plan_mode_requested: bool = False  # Track if enter_plan_mode was called
+        self.plan_mode_reason: Optional[str] = None  # Reason for plan mode request
+        self.plan_file_path: Optional[str] = None  # Path to the plan file (set when entering plan mode)
 
     @classmethod
     def get_instance(cls) -> "ModeState":
@@ -46,19 +45,63 @@ class ModeState:
         """Reset the singleton instance."""
         cls._instance = None
 
+    def reset_cycle(self) -> None:
+        """Reset per-cycle state (called on new user message)."""
+        self.plan_submitted = False
+        self.plan_mode_requested = False
+        self.plan_mode_reason = None
+
+    def approve_plan_mode(self) -> None:
+        """Approve plan mode entry (called when user approves)."""
+        self.current_mode = AgentMode.PLAN
+        self.plan_content = None
+        self.plan_mode_requested = False
+        self.plan_mode_reason = None
+        # plan_file_path should already be set by the caller
+
+    def reject_plan_mode(self) -> None:
+        """Reject plan mode entry (called when user rejects)."""
+        self.plan_mode_requested = False
+        self.plan_mode_reason = None
+        self.plan_file_path = None
+
+    def set_plan_file_path(self, path: str) -> None:
+        """Set the plan file path (called when entering plan mode)."""
+        self.plan_file_path = path
+
+    def get_plan_file_path(self) -> Optional[str]:
+        """Get the current plan file path."""
+        return self.plan_file_path
+
 
-class SwitchModeTool(BaseTool):
-    """Tool for switching between agent modes."""
+class EnterPlanModeTool(BaseTool):
+    """Tool for requesting to enter plan mode - REQUIRES USER CONSENT.
 
-    name = "switch_mode"
-    description = """Switch the agent to a different operating mode.
+    This follows Claude Code's pattern where entering plan mode is a proposal
+    that requires user approval, not an automatic switch.
+    """
 
-Modes:
-- exploration: General codebase exploration and understanding
-- planning: Feature planning and specification writing
-- coding: Active code editing and implementation
-- review: Code review and feedback
-- debug: Debugging and issue investigation"""
+    name = "enter_plan_mode"
+    description = """Request to enter plan mode for implementation planning.
+
+This tool REQUIRES USER APPROVAL before plan mode is activated.
+
+Use this proactively when you're about to start a non-trivial implementation task.
+Getting user sign-off on your approach before writing code prevents wasted effort.
+
+When to use:
+- New feature implementation requiring architectural decisions
+- Multiple valid approaches exist (user should choose)
+- Multi-file changes expected (more than 2-3 files)
+- Unclear requirements that need exploration first
+
+When NOT to use:
+- Single-line or few-line fixes
+- Trivial tasks with obvious implementation
+- Pure research/exploration (just explore directly)
+- Tasks with very specific, detailed instructions already provided
+
+The user will see your reason and can approve or reject entering plan mode."""
     category = ToolCategory.PLANNING
 
     def __init__(self, connection=None):
@@ -67,39 +110,47 @@ Modes:
 
     def execute(
         self,
-        mode: str,
-        context: Optional[str] = None,
+        reason: str = "",
+        **kwargs,
     ) -> ToolResult:
-        """Switch to a new mode.
+        """Request to enter plan mode (requires user approval).
 
         Args:
-            mode: Target mode name
-            context: Optional context for the new mode
+            reason: Why you want to enter plan mode (shown to user)
 
         Returns:
-            ToolResult indicating success
+            ToolResult requesting user approval
         """
-        try:
-            new_mode = AgentMode(mode.lower())
-        except ValueError:
-            valid_modes = [m.value for m in AgentMode]
+        state = ModeState.get_instance()
+
+        if state.current_mode == AgentMode.PLAN:
             return ToolResult.error_result(
-                f"Invalid mode: {mode}",
-                suggestions=[f"Valid modes: {', '.join(valid_modes)}"],
+                "Already in plan mode",
+                suggestions=["Use exit_plan to submit your plan for approval"],
             )
 
-        state = ModeState.get_instance()
-        old_mode = state.current_mode
-        state.current_mode = new_mode
+        # Check if already requested this cycle
+        if state.plan_mode_requested:
+            return ToolResult.error_result(
+                "Plan mode already requested. Wait for user response.",
+                suggestions=["Do not call enter_plan_mode again until user responds."],
+            )
 
-        if context:
-            state.mode_context[new_mode.value] = context
+        if not reason or not reason.strip():
+            return ToolResult.error_result(
+                "Reason is required",
+                suggestions=["Explain why you need plan mode (helps user decide)"],
+            )
+
+        # Mark as requested (not entered - user must approve)
+        state.plan_mode_requested = True
+        state.plan_mode_reason = reason.strip()
 
         return ToolResult.success_result(
             data={
-                "previous_mode": old_mode.value,
-                "current_mode": new_mode.value,
-                "context": context,
+                "status": "plan_mode_requested",
+                "reason": reason.strip(),
+                "message": "Plan mode requested. Waiting for user approval.",
             },
         )
 
@@ -107,17 +158,118 @@ Modes:
         """Get OpenAI function schema."""
         return self._make_schema(
             properties={
-                "mode": {
+                "reason": {
                     "type": "string",
-                    "enum": [m.value for m in AgentMode],
-                    "description": "Target mode to switch to",
+                    "description": "Why you want to enter plan mode (explain the task complexity)",
                 },
-                "context": {
+            },
+            required=["reason"],
+        )
+
+
+class ExitPlanModeTool(BaseTool):
+    """Tool for submitting a plan for user approval."""
+
+    name = "exit_plan"
+    description = """Submit an implementation plan for user approval.
+
+Use this tool to present a plan to the user for approval. The plan can come from:
+1. A Plan sub-agent you spawned via task(subagent_type="Plan", ...)
+2. Your own planning (if in plan mode)
+
+Pass the plan content as the 'plan' parameter.
+
+The user will either:
+- Approve: You can proceed with implementation
+- Reject: You'll receive feedback and can revise"""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(
+        self,
+        plan: Optional[str] = None,
+        **kwargs,
+    ) -> ToolResult:
+        """Submit plan for user approval.
+
+        Args:
+            plan: The plan content (required in code mode, optional in plan mode).
+
+        Returns:
+            ToolResult triggering user approval flow
+        """
+        state = ModeState.get_instance()
+
+        # Prevent multiple exit_plan calls per cycle
+        if state.plan_submitted:
+            return ToolResult.error_result(
+                "Plan already submitted. Wait for user approval.",
+                suggestions=["Do not call exit_plan again until user responds."],
+            )
+
+        # Get plan content from parameter or file
+        plan_content = plan
+
+        # In plan mode, try to read from plan file if not provided
+        if state.current_mode == AgentMode.PLAN:
+            if not plan_content or not plan_content.strip():
+                plan_file_path = state.get_plan_file_path()
+                if plan_file_path:
+                    try:
+                        from pathlib import Path
+                        plan_path = Path(plan_file_path)
+                        if plan_path.exists():
+                            plan_content = plan_path.read_text()
+                    except Exception as e:
+                        return ToolResult.error_result(
+                            f"Failed to read plan file: {e}",
+                            suggestions=[f"Write your plan to {plan_file_path} first"],
+                        )
+
+        # In code mode, plan content is required (from Plan subagent)
+        if state.current_mode == AgentMode.CODE:
+            if not plan_content or not plan_content.strip():
+                return ToolResult.error_result(
+                    "Plan content is required when submitting from code mode",
+                    suggestions=[
+                        "Pass the plan from your Plan sub-agent as the 'plan' parameter",
+                        "Example: exit_plan(plan=<plan_from_subagent>)",
+                    ],
+                )
+
+        if not plan_content or not plan_content.strip():
+            plan_file_path = state.get_plan_file_path() or "the plan file"
+            return ToolResult.error_result(
+                "Plan content is required",
+                suggestions=[
+                    f"Write your plan to {plan_file_path} using write_to_file, then call exit_plan",
+                    "Or pass the plan directly as a parameter",
+                ],
+            )
+
+        # Store plan content for reference and mark as submitted
+        state.plan_content = plan_content.strip()
+        state.plan_submitted = True
+
+        return ToolResult.success_result({
+            "status": "plan_submitted",
+            "plan": plan_content.strip(),
+            "message": "Plan submitted for user approval. Waiting for user response.",
+        })
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(
+            properties={
+                "plan": {
                     "type": "string",
-                    "description": "Optional context for the new mode",
+                    "description": "Optional: The implementation plan as markdown. If not provided, reads from the plan file.",
                 },
             },
-            required=["mode"],
+            required=[],
         )
 
 
@@ -125,14 +277,14 @@ class GetModeTool(BaseTool):
     """Tool for getting current agent mode."""
 
     name = "get_mode"
-    description = "Get the current agent operating mode and its context."
+    description = "Get the current agent operating mode (plan or code)."
     category = ToolCategory.PLANNING
 
     def __init__(self, connection=None):
         """Initialize without requiring connection."""
         self.connection = connection
 
-    def execute(self) -> ToolResult:
+    def execute(self, **kwargs) -> ToolResult:
         """Get current mode.
 
         Returns:
@@ -143,8 +295,8 @@ class GetModeTool(BaseTool):
         return ToolResult.success_result(
             data={
                 "current_mode": state.current_mode.value,
-                "context": state.mode_context.get(state.current_mode.value),
-                "available_modes": [m.value for m in AgentMode],
+                "has_plan": state.plan_content is not None,
+                "available_modes": SUPPORTED_MODES,
             },
         )
 

emdash_core/agent/tools/search.py

@@ -22,6 +22,7 @@ Useful for finding code related to concepts like "authentication", "database que
         entity_types: Optional[list[str]] = None,
         limit: int = 10,
         min_score: float = 0.5,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute semantic search.
 
@@ -121,6 +122,7 @@ More precise than semantic search when you know part of the name."""
         query: str,
         entity_types: Optional[list[str]] = None,
         limit: int = 10,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute text search.
 
@@ -215,6 +217,7 @@ Useful for finding code patterns, string literals, or specific implementations."
         file_pattern: Optional[str] = None,
         max_results: int = 50,
         context_lines: int = 2,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute grep search.
 
@@ -324,6 +327,7 @@ Common patterns:
         self,
         pattern: str,
         max_results: int = 100,
+        **kwargs,  # Ignore unexpected params from LLM
     ) -> ToolResult:
         """Execute glob search for files.
 

emdash_core/agent/tools/skill.py

@@ -0,0 +1,193 @@
+"""Skill invocation tool.
+
+Allows the agent to activate and invoke skills during task execution.
+Skills provide specialized instructions for repeatable tasks.
+"""
+
+from typing import Optional
+
+from .base import BaseTool, ToolResult, ToolCategory
+from ..skills import SkillRegistry, Skill
+
+
+class SkillTool(BaseTool):
+    """Tool for invoking skills.
+
+    Skills are markdown-based instruction files that teach the agent
+    how to perform specific, repeatable tasks. This tool allows
+    explicit skill invocation.
+    """
+
+    name = "skill"
+    description = """Invoke a skill for specialized task execution.
+
+Skills provide focused instructions for common tasks like:
+- commit: Generate commit messages following conventions
+- review-pr: Review PRs with code standards
+- security-review: Security-focused code review
+
+When you invoke a skill, you receive its instructions which you should follow.
+Use list_skills to see available skills."""
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(
+        self,
+        skill: str,
+        args: str = "",
+        **kwargs,
+    ) -> ToolResult:
+        """Invoke a skill.
+
+        Args:
+            skill: Name of the skill to invoke
+            args: Optional arguments to pass to the skill
+
+        Returns:
+            ToolResult with skill instructions
+        """
+        registry = SkillRegistry.get_instance()
+        skill_obj = registry.get_skill(skill)
+
+        if skill_obj is None:
+            available = registry.list_skills()
+            if available:
+                return ToolResult.error_result(
+                    f"Skill '{skill}' not found",
+                    suggestions=[f"Available skills: {', '.join(available)}"],
+                )
+            else:
+                return ToolResult.error_result(
+                    f"Skill '{skill}' not found. No skills are currently loaded.",
+                    suggestions=[
+                        "Create skills in .emdash/skills/<skill-name>/SKILL.md",
+                        "Skills are loaded from the .emdash/skills/ directory",
+                    ],
+                )
+
+        # Build the skill activation response
+        response_parts = [
+            f"# Skill Activated: {skill_obj.name}",
+            "",
+            f"**Description**: {skill_obj.description}",
+            "",
+        ]
+
+        if args:
+            response_parts.extend([
+                f"**Arguments**: {args}",
+                "",
+            ])
+
+        if skill_obj.tools:
+            response_parts.extend([
+                f"**Required tools**: {', '.join(skill_obj.tools)}",
+                "",
+            ])
+
+        response_parts.extend([
+            "---",
+            "",
+            skill_obj.instructions,
+        ])
+
+        return ToolResult.success_result(
+            data={
+                "skill_name": skill_obj.name,
+                "description": skill_obj.description,
+                "instructions": skill_obj.instructions,
+                "tools": skill_obj.tools,
+                "args": args,
+                "message": "\n".join(response_parts),
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        registry = SkillRegistry.get_instance()
+        available_skills = registry.list_skills()
+
+        description = self.description
+        if available_skills:
+            description += f"\n\nCurrently available skills: {', '.join(available_skills)}"
+
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": description,
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "skill": {
+                            "type": "string",
+                            "description": "Name of the skill to invoke",
+                        },
+                        "args": {
+                            "type": "string",
+                            "description": "Optional arguments for the skill (e.g., PR number, file path)",
+                        },
+                    },
+                    "required": ["skill"],
+                },
+            },
+        }
+
+
+class ListSkillsTool(BaseTool):
+    """Tool for listing available skills."""
+
+    name = "list_skills"
+    description = "List all available skills and their descriptions."
+    category = ToolCategory.PLANNING
+
+    def __init__(self, connection=None):
+        """Initialize without requiring connection."""
+        self.connection = connection
+
+    def execute(self, **kwargs) -> ToolResult:
+        """List available skills.
+
+        Returns:
+            ToolResult with list of skills
+        """
+        registry = SkillRegistry.get_instance()
+        skills = registry.get_all_skills()
+
+        if not skills:
+            return ToolResult.success_result(
+                data={
+                    "skills": [],
+                    "message": "No skills loaded. Create skills in .emdash/skills/<skill-name>/SKILL.md",
+                },
+            )
+
+        skills_list = []
+        for skill in skills.values():
+            skills_list.append({
+                "name": skill.name,
+                "description": skill.description,
+                "user_invocable": skill.user_invocable,
+                "tools": skill.tools,
+            })
+
+        # Build human-readable message
+        lines = ["# Available Skills", ""]
+        for s in skills_list:
+            invocable = f" (invoke with /{s['name']})" if s["user_invocable"] else ""
+            lines.append(f"- **{s['name']}**: {s['description']}{invocable}")
+
+        return ToolResult.success_result(
+            data={
+                "skills": skills_list,
+                "count": len(skills_list),
+                "message": "\n".join(lines),
+            },
+        )
+
+    def get_schema(self) -> dict:
+        """Get OpenAI function schema."""
+        return self._make_schema(properties={}, required=[])