clink-cli 0.2.1__py3-none-any.whl

tools/workflow/workflow_mixin.py

@@ -0,0 +1,1195 @@
+"""
+Workflow Mixin for PAL MCP Tools
+
+This module provides a sophisticated workflow-based pattern that enables tools to
+perform multi-step work with structured findings and expert analysis.
+
+Key Components:
+- BaseWorkflowMixin: Abstract base class providing comprehensive workflow functionality
+
+The workflow pattern enables tools like debug, precommit, and codereview to perform
+systematic multi-step work with pause/resume capabilities, context-aware file embedding,
+and seamless integration with external AI models for expert analysis.
+
+Features:
+- Multi-step workflow orchestration with pause/resume
+- Context-aware file embedding optimization
+- Expert analysis integration with token budgeting
+- Conversation memory and threading support
+- Proper inheritance-based architecture (no hasattr/getattr)
+- Comprehensive type annotations for IDE support
+"""
+
+import json
+import logging
+import os
+import re
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from mcp.types import TextContent
+from pydantic import ValidationError
+
+from clink.contracts import BackendError
+from config import MCP_PROMPT_SIZE_LIMIT
+from utils.call_state import StateError
+
+from ..shared.base_models import ConsolidatedFindings
+from ..shared.exceptions import ToolExecutionError
+
+logger = logging.getLogger(__name__)
+
+
+class BaseWorkflowMixin(ABC):
+    """
+    Abstract base class providing guided workflow functionality for tools.
+
+    This class implements a sophisticated workflow pattern where the CLI performs
+    systematic local work before calling external models for expert analysis.
+    Tools can inherit from this class to gain comprehensive workflow capabilities.
+
+    Architecture:
+    - Uses proper inheritance patterns instead of hasattr/getattr
+    - Provides hook methods with default implementations
+    - Requires abstract methods to be implemented by subclasses
+    - Fully type-annotated for excellent IDE support
+
+    Context-Aware File Embedding:
+    - Intermediate steps: Only reference file names (saves the CLI's context)
+    - Final steps: Embed full file content for expert analysis
+    - Integrates with existing token budgeting infrastructure
+
+    Requirements:
+    This class expects to be used with BaseTool and requires implementation of:
+    - get_system_prompt()
+    - get_default_temperature()
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.work_history: list[dict[str, Any]] = []
+        self.consolidated_findings: ConsolidatedFindings = ConsolidatedFindings()
+        self.initial_request: Optional[str] = None
+
+    # ================================================================================
+    # Abstract Methods - Required Implementation by BaseTool or Subclasses
+    # ================================================================================
+
+    @abstractmethod
+    def get_name(self) -> str:
+        """Return the name of this tool. Usually provided by BaseTool."""
+        pass
+
+    @abstractmethod
+    def get_workflow_request_model(self) -> type:
+        """Return the request model class for this workflow tool."""
+        pass
+
+    @abstractmethod
+    def get_system_prompt(self) -> str:
+        """Return the system prompt for this tool. Usually provided by BaseTool."""
+        pass
+
+    @abstractmethod
+    def get_language_instruction(self) -> str:
+        """Return the language instruction for localization. Usually provided by BaseTool."""
+        pass
+
+    @abstractmethod
+    def get_default_temperature(self) -> float:
+        """Return the default temperature for this tool. Usually provided by BaseTool."""
+        pass
+
+    # ================================================================================
+    # Abstract Methods - Tool-Specific Implementation Required
+    # ================================================================================
+
+    @abstractmethod
+    def get_work_steps(self, request: Any) -> list[str]:
+        """Define tool-specific work steps and criteria"""
+        pass
+
+    @abstractmethod
+    def get_required_actions(
+        self, step_number: int, confidence: str, findings: str, total_steps: int, request=None
+    ) -> list[str]:
+        """Define required actions for each work phase.
+
+        Args:
+            step_number: Current step (1-based)
+            confidence: Current confidence level (exploring, low, medium, high, certain)
+            findings: Current findings text
+            total_steps: Total estimated steps for this work
+            request: Optional request object for continuation-aware decisions
+
+        Returns:
+            List of specific actions the CLI should take before calling tool again
+        """
+        pass
+
+    # ================================================================================
+    # Hook Methods - Default Implementations with Override Capability
+    # ================================================================================
+
+    def should_call_expert_analysis(self, consolidated_findings: ConsolidatedFindings, request=None) -> bool:
+        """
+        Decide when to call external model based on tool-specific criteria.
+
+        Default implementation for tools that don't use expert analysis.
+        Override this for tools that do use expert analysis.
+
+        Args:
+            consolidated_findings: Findings from workflow steps
+            request: Current request object (optional for backwards compatibility)
+        """
+        if not self.requires_expert_analysis():
+            return False
+
+        # Check if user requested to skip assistant model
+        if request and not self.get_request_use_assistant_model(request):
+            return False
+
+        # Default logic for tools that support expert analysis
+        return (
+            len(consolidated_findings.relevant_files) > 0
+            or len(consolidated_findings.findings) >= 2
+            or len(consolidated_findings.issues_found) > 0
+        )
+
+    def prepare_expert_analysis_context(self, consolidated_findings: ConsolidatedFindings) -> str:
+        """
+        Prepare context for external model call.
+
+        Default implementation for tools that don't use expert analysis.
+        Override this for tools that do use expert analysis.
+        """
+        if not self.requires_expert_analysis():
+            return ""
+
+        # Default context preparation
+        context_parts = [
+            f"=== {self.get_name().upper()} WORK SUMMARY ===",
+            f"Total steps: {len(consolidated_findings.findings)}",
+            f"Files examined: {len(consolidated_findings.files_checked)}",
+            f"Relevant files: {len(consolidated_findings.relevant_files)}",
+            "",
+            "=== WORK PROGRESSION ===",
+        ]
+
+        for finding in consolidated_findings.findings:
+            context_parts.append(finding)
+
+        return "\n".join(context_parts)
+
+    def requires_expert_analysis(self) -> bool:
+        """
+        Override this to completely disable expert analysis for the tool.
+
+        Returns True if the tool supports expert analysis (default).
+        Returns False if the tool is self-contained (like planner).
+        """
+        return True
+
+    def should_include_files_in_expert_prompt(self) -> bool:
+        """
+        Whether to include file content in the expert analysis prompt.
+        Override this to return True if your tool needs files in the prompt.
+        """
+        return False
+
+    def should_embed_system_prompt(self) -> bool:
+        """
+        Whether to embed the system prompt in the main prompt.
+        Override this to return True if your tool needs the system prompt embedded.
+        """
+        return False
+
+    def get_expert_thinking_mode(self) -> str:
+        """
+        Get the thinking mode for expert analysis.
+        Override this to customize the thinking mode.
+        """
+        return "high"
+
+    def get_request_temperature(self, request) -> float:
+        """Get temperature from request. Override for custom temperature handling."""
+        try:
+            return request.temperature if request.temperature is not None else self.get_default_temperature()
+        except AttributeError:
+            return self.get_default_temperature()
+
+    def get_request_thinking_mode(self, request) -> str:
+        """Get thinking mode from request. Override for custom thinking mode handling."""
+        try:
+            return request.thinking_mode if request.thinking_mode is not None else self.get_expert_thinking_mode()
+        except AttributeError:
+            return self.get_expert_thinking_mode()
+
+    def get_expert_analysis_instruction(self) -> str:
+        """
+        Get the instruction to append after the expert context.
+        Override this to provide tool-specific instructions.
+        """
+        return "Please provide expert analysis based on the investigation findings."
+
+    def get_request_use_assistant_model(self, request) -> bool:
+        """
+        Get use_assistant_model from request. Override for custom assistant model handling.
+
+        Args:
+            request: Current request object
+
+        Returns:
+            True if assistant model should be used, False otherwise
+        """
+        try:
+            return request.use_assistant_model if request.use_assistant_model is not None else True
+        except AttributeError:
+            return True
+
+    def get_step_guidance_message(self, request) -> str:
+        """
+        Get step guidance message. Override for tool-specific guidance.
+        Default implementation uses required actions.
+        """
+        required_actions = self.get_required_actions(
+            request.step_number, self.get_request_confidence(request), request.findings, request.total_steps, request
+        )
+
+        next_step_number = request.step_number + 1
+        return (
+            f"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. "
+            f"You MUST first work using appropriate tools. "
+            f"REQUIRED ACTIONS before calling {self.get_name()} step {next_step_number}:\n"
+            + "\n".join(f"{i + 1}. {action}" for i, action in enumerate(required_actions))
+            + f"\n\nOnly call {self.get_name()} again with step_number: {next_step_number} "
+            f"AFTER completing this work."
+        )
+
+    def wants_line_numbers_by_default(self) -> bool:
+        """
+        Whether this tool wants line numbers in file content by default.
+        Override this to customize line number behavior.
+        """
+        return True  # Most workflow tools benefit from line numbers for analysis
+
+    # ================================================================================
+    # Context-Aware File Embedding - Core Implementation
+    # ================================================================================
+
+    def _handle_workflow_file_context(self, request: Any, arguments: dict[str, Any]) -> None:
+        """Keep investigation steps local; expert calls embed after path admission."""
+        self._embedded_file_content = ""
+        self._file_reference_note = ""
+        self._actually_processed_files = []
+        self._reference_workflow_files(request)
+
+    def _reference_workflow_files(self, request: Any) -> None:
+        """
+        Reference file names without embedding content for intermediate steps.
+        Saves the CLI's context while still providing file awareness.
+        """
+        # Workflow tools use relevant_files, not files
+        request_files = self.get_request_relevant_files(request)
+        logger.debug(
+            f"[WORKFLOW_FILES] {self.get_name()}: _reference_workflow_files called with {len(request_files)} relevant_files"
+        )
+
+        if not request_files:
+            logger.debug(f"[WORKFLOW_FILES] {self.get_name()}: No files to reference, skipping")
+            return
+
+        # Store file references for conversation context
+        self._referenced_files = request_files
+
+        # Create a simple reference note
+        file_names = [os.path.basename(f) for f in request_files]
+        reference_note = f"Files referenced in this step: {', '.join(file_names)}\n"
+
+        self._file_reference_note = reference_note
+        logger.debug("workflow_files_referenced tool=%s count=%d", self.get_name(), len(request_files))
+
+        logger.info(
+            f"[WORKFLOW_FILES] {self.get_name()}: Referenced {len(request_files)} files without embedding content"
+        )
+
+    # ================================================================================
+    # Main Workflow Orchestration
+    # ================================================================================
+
+    async def execute_workflow(self, arguments: dict[str, Any]) -> list[TextContent]:
+        """
+        Main workflow orchestration following debug tool pattern.
+
+        Comprehensive workflow implementation that handles all common patterns:
+        1. Request validation and step management
+        2. Continuation and backtracking support
+        3. Step data processing and consolidation
+        4. Tool-specific field mapping and customization
+        5. Completion logic with optional expert analysis
+        6. Generic "certain confidence" handling
+        7. Step guidance and required actions
+        8. Conversation memory integration
+        """
+
+        try:
+            # Store arguments for access by helper methods
+            self._current_arguments = arguments
+
+            # Validate request using tool-specific model
+            request = self.get_workflow_request_model()(**arguments)
+
+            # Validate step field size (basic validation for workflow instructions)
+            # If step is too large, user should use shorter instructions and put details in files
+            step_content = request.step
+            if step_content and len(step_content.encode("utf-8")) > MCP_PROMPT_SIZE_LIMIT:
+                from tools.models import ToolOutput
+
+                error_output = ToolOutput(
+                    status="error",
+                    metadata={"code": "input_limit", "remedy": "Split or narrow the workflow step."},
+                    content="Step instructions are too long. Please use shorter instructions and provide detailed context via file paths instead.",
+                    content_type="text",
+                )
+                raise ToolExecutionError(error_output.model_dump_json())
+
+            # Validate file paths for security (same as base tool)
+            # Use try/except instead of hasattr as per coding standards
+            try:
+                path_error = self.validate_file_paths(request)
+                if path_error:
+                    from tools.models import ToolOutput
+
+                    error_output = ToolOutput(
+                        status="error",
+                        content=path_error,
+                        content_type="text",
+                    )
+                    logger.error("workflow_path_validation_failed tool=%s", self.get_name())
+                    raise ToolExecutionError(error_output.model_dump_json())
+            except AttributeError:
+                # validate_file_paths method not available - skip validation
+                pass
+
+            from utils.call_state import get_current_call
+
+            call = get_current_call()
+            continuation_id = call.continuation_id if call is not None else request.continuation_id
+            state = call.workflow_state if call is not None else {}
+            self.work_history = list(state.get("work_history", []))
+            self.initial_request = state.get("initial_request")
+            for name in self.get_workflow_state_fields():
+                if name in state:
+                    setattr(self, name, state[name])
+            self._reprocess_consolidated_findings()
+
+            # Adjust total steps if needed
+            if request.step_number > request.total_steps:
+                request.total_steps = request.step_number
+
+            if not self.work_history:
+                self.initial_request = request.step
+                self.store_initial_issue(request.step)
+
+            # Process work step - allow tools to customize field mapping
+            step_data = self.prepare_step_data(request)
+
+            # Store in history
+            self.work_history.append(step_data)
+
+            # Update consolidated findings
+            self._update_consolidated_findings(step_data)
+
+            # Handle file context appropriately based on workflow phase
+            self._handle_workflow_file_context(request, arguments)
+
+            # Build response with tool-specific customization
+            response_data = self.build_base_response(request, continuation_id)
+
+            # If work is complete, handle completion logic
+            if not request.next_step_required:
+                response_data = await self.handle_work_completion(response_data, request, arguments)
+            else:
+                # Force CLI to work before calling tool again
+                response_data = self.handle_work_continuation(response_data, request)
+
+            # Allow tools to customize the final response
+            response_data = self.customize_workflow_response(response_data, request)
+
+            # Add bounded backend metadata to the workflow response
+            self._add_workflow_metadata(response_data, arguments)
+
+            # Store in conversation memory
+            if continuation_id:
+                self.store_conversation_turn(continuation_id, response_data, request)
+
+            payload = json.dumps(response_data, indent=2, ensure_ascii=False)
+            if response_data.get("status") == "error":
+                raise ToolExecutionError(payload)
+            return [TextContent(type="text", text=payload)]
+
+        except (ToolExecutionError, StateError):
+            raise
+        except BackendError as exc:
+            error_data = {"status": "error", "content": str(exc), "metadata": exc.to_dict()}
+            raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from None
+        except (ValidationError, ValueError):
+            error_data = {
+                "status": "error",
+                "content": "Request validation failed; check the declared fields.",
+                "metadata": {"code": "invalid_request", "tool_name": self.get_name()},
+            }
+            raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from None
+        except Exception as exc:
+            logger.error("workflow_execution_failed tool=%s error_type=%s", self.get_name(), type(exc).__name__)
+            error_data = {
+                "status": "error",
+                "content": "The workflow could not complete this request.",
+                "metadata": {"code": "tool_error", "tool_name": self.get_name(), "error_type": type(exc).__name__},
+            }
+            raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from None
+
+    # Hook methods for tool customization
+
+    def prepare_step_data(self, request) -> dict:
+        """
+        Prepare step data from request. Tools can override to customize field mapping.
+        """
+        step_data = {
+            "step": request.step,
+            "step_number": request.step_number,
+            "findings": request.findings,
+            "files_checked": self.get_request_files_checked(request),
+            "relevant_files": self.get_request_relevant_files(request),
+            "relevant_context": self.get_request_relevant_context(request),
+            "issues_found": self.get_request_issues_found(request),
+            "confidence": self.get_request_confidence(request),
+            "hypothesis": self.get_request_hypothesis(request),
+            "images": self.get_request_images(request),
+        }
+        return step_data
+
+    def build_base_response(self, request, continuation_id: str = None) -> dict:
+        """
+        Build the base response structure. Tools can override for custom response fields.
+        """
+        response_data = {
+            "status": f"{self.get_name()}_in_progress",
+            "step_number": request.step_number,
+            "total_steps": request.total_steps,
+            "next_step_required": request.next_step_required,
+            f"{self.get_name()}_status": {
+                "files_checked": len(self.consolidated_findings.files_checked),
+                "relevant_files": len(self.consolidated_findings.relevant_files),
+                "relevant_context": len(self.consolidated_findings.relevant_context),
+                "issues_found": len(self.consolidated_findings.issues_found),
+                "images_collected": len(self.consolidated_findings.images),
+                "current_confidence": self.get_request_confidence(request),
+            },
+        }
+
+        if continuation_id:
+            response_data["continuation_id"] = continuation_id
+
+        # Add file context information based on workflow phase
+        embedded_content = self.get_embedded_file_content()
+        reference_note = self.get_file_reference_note()
+        processed_files = self.get_actually_processed_files()
+
+        logger.debug(
+            f"[WORKFLOW_FILES] {self.get_name()}: Building response - has embedded_content: {bool(embedded_content)}, has reference_note: {bool(reference_note)}"
+        )
+
+        # Prioritize embedded content over references for final steps
+        if embedded_content:
+            # Final step - include embedded file information
+            logger.debug(f"[WORKFLOW_FILES] {self.get_name()}: Adding fully_embedded file context")
+            response_data["file_context"] = {
+                "type": "fully_embedded",
+                "files_embedded": len(processed_files),
+                "context_optimization": "Full file content embedded for expert analysis",
+            }
+        elif reference_note:
+            # Intermediate step - include file reference note
+            logger.debug(f"[WORKFLOW_FILES] {self.get_name()}: Adding reference_only file context")
+            response_data["file_context"] = {
+                "type": "reference_only",
+                "note": reference_note,
+                "context_optimization": "Files referenced but not embedded to preserve the context window",
+            }
+
+        return response_data
+
+    def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:
+        """
+        Determine if expert analysis should be skipped due to high certainty.
+
+        Default: False (always call expert analysis)
+        Override in tools like debug to check for "certain" confidence.
+        """
+        return False
+
+    def handle_completion_without_expert_analysis(self, request, consolidated_findings) -> dict:
+        """
+        Handle completion when skipping expert analysis.
+
+        Tools can override this for custom high-confidence completion handling.
+        Default implementation provides generic response.
+        """
+        work_summary = self.prepare_work_summary()
+        continuation_id = self.get_request_continuation_id(request)
+
+        response_data = {
+            "status": self.get_completion_status(),
+            f"complete_{self.get_name()}": {
+                "initial_request": self.get_initial_request(request.step),
+                "steps_taken": len(consolidated_findings.findings),
+                "files_examined": list(consolidated_findings.files_checked),
+                "relevant_files": list(consolidated_findings.relevant_files),
+                "relevant_context": list(consolidated_findings.relevant_context),
+                "work_summary": work_summary,
+                "final_analysis": self.get_final_analysis_from_request(request),
+                "confidence_level": self.get_confidence_level(request),
+            },
+            "next_steps": self.get_completion_message(),
+            "skip_expert_analysis": True,
+            "expert_analysis": {
+                "status": self.get_skip_expert_analysis_status(),
+                "reason": self.get_skip_reason(),
+            },
+        }
+
+        if continuation_id:
+            response_data["continuation_id"] = continuation_id
+
+        return response_data
+
+    # ================================================================================
+    # Inheritance Hook Methods - Replace hasattr/getattr Anti-patterns
+    # ================================================================================
+
+    def get_request_confidence(self, request: Any) -> str:
+        """Get confidence from request. Override for custom confidence handling."""
+        try:
+            return request.confidence or "low"
+        except AttributeError:
+            return "low"
+
+    def get_request_relevant_context(self, request: Any) -> list[str]:
+        """Get relevant context from request. Override for custom field mapping."""
+        try:
+            return request.relevant_context or []
+        except AttributeError:
+            return []
+
+    def get_request_issues_found(self, request: Any) -> list[str]:
+        """Get issues found from request. Override for custom field mapping."""
+        try:
+            return request.issues_found or []
+        except AttributeError:
+            return []
+
+    def get_request_hypothesis(self, request: Any) -> Optional[str]:
+        """Get hypothesis from request. Override for custom field mapping."""
+        try:
+            return request.hypothesis
+        except AttributeError:
+            return None
+
+    def get_request_images(self, request: Any) -> list[str]:
+        """Get images from request. Override for custom field mapping."""
+        try:
+            return request.images or []
+        except AttributeError:
+            return []
+
+    # File Context Access Methods
+
+    def get_embedded_file_content(self) -> str:
+        """Get embedded file content. Returns empty string if not available."""
+        try:
+            return self._embedded_file_content or ""
+        except AttributeError:
+            return ""
+
+    def get_file_reference_note(self) -> str:
+        """Get file reference note. Returns empty string if not available."""
+        try:
+            return self._file_reference_note or ""
+        except AttributeError:
+            return ""
+
+    def get_actually_processed_files(self) -> list[str]:
+        """Get list of actually processed files. Returns empty list if not available."""
+        try:
+            return self._actually_processed_files or []
+        except AttributeError:
+            return []
+
+    def get_request_model_name(self, request: Any) -> Optional[str]:
+        return request.model
+
+    def get_request_continuation_id(self, request: Any) -> Optional[str]:
+        """Get continuation ID from request. Override for custom continuation handling."""
+        try:
+            return request.continuation_id
+        except AttributeError:
+            return None
+
+    def get_request_next_step_required(self, request: Any) -> bool:
+        """Get next step required from request. Override for custom step handling."""
+        try:
+            return request.next_step_required
+        except AttributeError:
+            return True
+
+    def get_request_step_number(self, request: Any) -> int:
+        """Get step number from request. Override for custom step handling."""
+        try:
+            return request.step_number or 1
+        except AttributeError:
+            return 1
+
+    def get_request_relevant_files(self, request: Any) -> list[str]:
+        """Get relevant files from request. Override for custom file handling."""
+        try:
+            return request.relevant_files or []
+        except AttributeError:
+            return []
+
+    def get_request_files_checked(self, request: Any) -> list[str]:
+        """Get files checked from request. Override for custom file handling."""
+        try:
+            return request.files_checked or []
+        except AttributeError:
+            return []
+
+    def get_current_arguments(self) -> dict[str, Any]:
+        """Get current arguments. Returns empty dict if not available."""
+        try:
+            return self._current_arguments or {}
+        except AttributeError:
+            return {}
+
+    def store_initial_issue(self, step_description: str):
+        """Store initial issue description. Override for custom storage."""
+        # Default implementation - tools can override to store differently
+        self.initial_issue = step_description
+
+    def get_initial_request(self, fallback_step: str) -> str:
+        """Get initial request description. Override for custom retrieval."""
+        try:
+            return self.initial_request or fallback_step
+        except AttributeError:
+            return fallback_step
+
+    # Default implementations for inheritance hooks
+
+    def prepare_work_summary(self) -> str:
+        """Prepare work summary. Override for custom implementation."""
+        return f"Completed {len(self.consolidated_findings.findings)} work steps"
+
+    def get_completion_status(self) -> str:
+        """Get completion status. Override for tool-specific status."""
+        return "high_confidence_completion"
+
+    def get_final_analysis_from_request(self, request):
+        """Extract final analysis from request. Override for tool-specific fields."""
+        return self.get_request_hypothesis(request)
+
+    def get_confidence_level(self, request) -> str:
+        """Get confidence level. Override for tool-specific confidence handling."""
+        return self.get_request_confidence(request) or "high"
+
+    def get_completion_message(self) -> str:
+        """Get completion message. Override for tool-specific messaging."""
+        return (
+            f"{self.get_name().capitalize()} complete with high confidence. Present results "
+            "and proceed with implementation without requiring further consultation."
+        )
+
+    def get_skip_reason(self) -> str:
+        """Get reason for skipping expert analysis. Override for tool-specific reasons."""
+        return f"{self.get_name()} completed with sufficient confidence"
+
+    def get_skip_expert_analysis_status(self) -> str:
+        """Get status for skipped expert analysis. Override for tool-specific status."""
+        return "skipped_by_tool_design"
+
+    def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:
+        """
+        Get the message to show when work is complete.
+        Tools can override for custom messaging.
+
+        Args:
+            expert_analysis_used: True if expert analysis was successfully executed
+        """
+        base_message = (
+            f"{self.get_name().upper()} IS COMPLETE. You MUST now summarize and present ALL key findings, confirmed "
+            "hypotheses, and exact recommended solutions. Clearly identify the most likely root cause and "
+            "provide concrete, actionable implementation guidance. Highlight affected code paths and display "
+            "reasoning that led to this conclusion—make it easy for a developer to understand exactly where "
+            "the problem lies."
+        )
+
+        # Add expert analysis guidance only when expert analysis was actually used
+        if expert_analysis_used:
+            expert_guidance = self.get_expert_analysis_guidance()
+            if expert_guidance:
+                return f"{base_message}\n\n{expert_guidance}"
+
+        return base_message
+
+    def get_expert_analysis_guidance(self) -> str:
+        """
+        Get additional guidance for handling expert analysis results.
+
+        Subclasses can override this to provide specific instructions about how
+        to validate and use expert analysis findings. Returns empty string by default.
+
+        When expert analysis is called, this guidance will be:
+        1. Appended to the completion next steps message
+        2. Added as "important_considerations" field in the response data
+
+        Example implementation:
+        ```python
+        def get_expert_analysis_guidance(self) -> str:
+            return (
+                "IMPORTANT: Expert analysis provided above. You MUST validate "
+                "the expert findings rather than accepting them blindly. "
+                "Cross-reference with your own investigation and ensure "
+                "recommendations align with the codebase context."
+            )
+        ```
+
+        Returns:
+            Additional guidance text or empty string if no guidance needed
+        """
+        return ""
+
+    def customize_workflow_response(self, response_data: dict, request) -> dict:
+        """
+        Allow tools to customize the workflow response before returning.
+
+        Tools can override this to add tool-specific fields, modify status names,
+        customize field mapping, etc. Default implementation returns unchanged.
+        """
+        # Ensure file context information is preserved in all response paths
+        if not response_data.get("file_context"):
+            embedded_content = self.get_embedded_file_content()
+            reference_note = self.get_file_reference_note()
+            processed_files = self.get_actually_processed_files()
+
+            # Prioritize embedded content over references for final steps
+            if embedded_content:
+                response_data["file_context"] = {
+                    "type": "fully_embedded",
+                    "files_embedded": len(processed_files),
+                    "context_optimization": "Full file content embedded for expert analysis",
+                }
+            elif reference_note:
+                response_data["file_context"] = {
+                    "type": "reference_only",
+                    "note": reference_note,
+                    "context_optimization": "Files referenced but not embedded to preserve the context window",
+                }
+
+        return response_data
+
+    def store_conversation_turn(self, continuation_id: str, response_data: dict, request):
+        """Snapshot workflow data; the outer call transaction records history once."""
+        from utils.call_state import get_current_call
+
+        call = get_current_call()
+        if call is not None:
+            fields = self.get_workflow_state_fields()
+            state = {name: getattr(self, name) for name in fields if name in self.__dict__}
+            state["work_history"] = self.work_history
+            state["initial_request"] = self.initial_request
+            call.set_workflow_state(state)
+
+    def get_workflow_state_fields(self) -> tuple[str, ...]:
+        """Explicit persisted fields for existing workflows, including branches/configuration."""
+        return (
+            "branches",
+            "trace_config",
+            "security_config",
+            "analysis_config",
+            "refactor_config",
+            "git_config",
+            "review_config",
+            "stored_request_params",
+            "initial_issue",
+            "initial_planning_description",
+            "initial_tracing_description",
+        )
+
+    def _add_workflow_metadata(self, response_data: dict, arguments: dict[str, Any]) -> None:
+        metadata = response_data.setdefault("metadata", {})
+        metadata["tool_name"] = self.get_name()
+        metadata.update(getattr(self, "_backend_metadata", {}))
+
+    def _extract_clean_workflow_content_for_history(self, response_data: dict) -> str:
+        """
+        Extract clean content from workflow response suitable for conversation history.
+
+        This method removes internal workflow metadata, continuation offers, and
+        status information that should not appear when the conversation is
+        reconstructed for expert models or other tools.
+
+        Args:
+            response_data: The full workflow response data
+
+        Returns:
+            str: Clean content suitable for conversation history storage
+        """
+        # Create a clean copy with only essential content for conversation history
+        clean_data = {}
+
+        # Include core content if present
+        if "content" in response_data:
+            clean_data["content"] = response_data["content"]
+
+        # Include expert analysis if present (but clean it)
+        if "expert_analysis" in response_data:
+            expert_analysis = response_data["expert_analysis"]
+            if isinstance(expert_analysis, dict):
+                # Only include the actual analysis content, not metadata
+                clean_expert = {}
+                if "raw_analysis" in expert_analysis:
+                    clean_expert["analysis"] = expert_analysis["raw_analysis"]
+                elif "content" in expert_analysis:
+                    clean_expert["analysis"] = expert_analysis["content"]
+                if clean_expert:
+                    clean_data["expert_analysis"] = clean_expert
+
+        # Include findings/issues if present (core workflow output)
+        if "complete_analysis" in response_data:
+            complete_analysis = response_data["complete_analysis"]
+            if isinstance(complete_analysis, dict):
+                clean_complete = {}
+                # Include essential analysis data without internal metadata
+                for key in ["findings", "issues_found", "relevant_context", "insights"]:
+                    if key in complete_analysis:
+                        clean_complete[key] = complete_analysis[key]
+                if clean_complete:
+                    clean_data["analysis_summary"] = clean_complete
+
+        # Include step information for context but remove internal workflow metadata
+        if "step_number" in response_data:
+            clean_data["step_info"] = {
+                "step": response_data.get("step", ""),
+                "step_number": response_data.get("step_number", 1),
+                "total_steps": response_data.get("total_steps", 1),
+            }
+
+        # Exclude problematic fields that should never appear in conversation history:
+        # - continuation_id (confuses LLMs with old IDs)
+        # - status (internal workflow state)
+        # - next_step_required (internal control flow)
+        # - analysis_status (internal tracking)
+        # - file_context (internal optimization info)
+        # - required_actions (internal workflow instructions)
+
+        return json.dumps(clean_data, indent=2, ensure_ascii=False)
+
+    # Core workflow logic methods
+
+    async def handle_work_completion(self, response_data: dict, request, arguments: dict) -> dict:
+        """
+        Handle work completion logic - expert analysis decision and response building.
+        """
+        response_data[f"{self.get_name()}_complete"] = True
+
+        # Check if tool wants to skip expert analysis due to high certainty
+        if self.requires_expert_analysis() and not self.get_request_use_assistant_model(request):
+            response_data.update(
+                {
+                    "status": "local_work_complete",
+                    "skip_expert_analysis": True,
+                    "expert_analysis": {"status": "skipped_by_user", "reason": "use_assistant_model=false"},
+                    "next_steps": self.get_completion_next_steps_message(expert_analysis_used=False),
+                }
+            )
+        elif self.should_skip_expert_analysis(request, self.consolidated_findings):
+            # Handle completion without expert analysis
+            completion_response = self.handle_completion_without_expert_analysis(request, self.consolidated_findings)
+            response_data.update(completion_response)
+        elif self.requires_expert_analysis() and self.should_call_expert_analysis(self.consolidated_findings, request):
+            # Standard expert analysis path
+            response_data["status"] = "calling_expert_analysis"
+
+            # Call expert analysis
+            expert_analysis = await self._call_expert_analysis(arguments, request)
+            response_data["expert_analysis"] = expert_analysis
+
+            # Handle special expert analysis statuses
+            if isinstance(expert_analysis, dict) and expert_analysis.get("status") in [
+                "files_required_to_continue",
+                "investigation_paused",
+                "refactoring_paused",
+            ]:
+                # Promote the special status to the main response
+                special_status = expert_analysis["status"]
+                response_data["status"] = special_status
+                response_data["content"] = expert_analysis.get(
+                    "raw_analysis", json.dumps(expert_analysis, ensure_ascii=False)
+                )
+                del response_data["expert_analysis"]
+
+                # Update next steps for special status
+                if special_status == "files_required_to_continue":
+                    response_data["next_steps"] = "Provide the requested files and continue the analysis."
+                else:
+                    response_data["next_steps"] = expert_analysis.get(
+                        "next_steps", "Continue based on expert analysis."
+                    )
+            elif isinstance(expert_analysis, dict) and expert_analysis.get("status") == "analysis_error":
+                # Expert analysis failed - promote error status
+                response_data["status"] = "error"
+                response_data["content"] = expert_analysis.get("error", "Expert analysis failed")
+                response_data["content_type"] = "text"
+                response_data.setdefault("metadata", {}).update(expert_analysis.get("metadata", {}))
+                del response_data["expert_analysis"]
+            else:
+                # Expert analysis was successfully executed - include expert guidance
+                response_data["next_steps"] = self.get_completion_next_steps_message(expert_analysis_used=True)
+
+                # Add expert analysis guidance as important considerations
+                expert_guidance = self.get_expert_analysis_guidance()
+                if expert_guidance:
+                    response_data["important_considerations"] = expert_guidance
+
+            # Prepare complete work summary
+            work_summary = self._prepare_work_summary()
+            response_data[f"complete_{self.get_name()}"] = {
+                "initial_request": self.get_initial_request(request.step),
+                "steps_taken": len(self.work_history),
+                "files_examined": list(self.consolidated_findings.files_checked),
+                "relevant_files": list(self.consolidated_findings.relevant_files),
+                "relevant_context": list(self.consolidated_findings.relevant_context),
+                "issues_found": self.consolidated_findings.issues_found,
+                "work_summary": work_summary,
+            }
+        else:
+            # Tool doesn't require expert analysis or local work was sufficient
+            if not self.requires_expert_analysis():
+                # Tool is self-contained (like planner)
+                response_data["status"] = f"{self.get_name()}_complete"
+                response_data["next_steps"] = (
+                    f"{self.get_name().capitalize()} work complete. Present results to the user."
+                )
+            else:
+                # Local work was sufficient for tools that support expert analysis
+                response_data["status"] = "local_work_complete"
+                response_data["next_steps"] = (
+                    f"Local {self.get_name()} complete with sufficient confidence. Present findings "
+                    "and recommendations to the user based on the work results."
+                )
+
+        return response_data
+
+    def handle_work_continuation(self, response_data: dict, request) -> dict:
+        """
+        Handle work continuation - force pause and provide guidance.
+        """
+        response_data["status"] = f"pause_for_{self.get_name()}"
+        response_data[f"{self.get_name()}_required"] = True
+
+        # Get tool-specific required actions
+        required_actions = self.get_required_actions(
+            request.step_number, self.get_request_confidence(request), request.findings, request.total_steps, request
+        )
+        response_data["required_actions"] = required_actions
+
+        # Generate step guidance
+        response_data["next_steps"] = self.get_step_guidance_message(request)
+
+        return response_data
+
+    def _update_consolidated_findings(self, step_data: dict):
+        """Update consolidated findings with new step data"""
+        self.consolidated_findings.files_checked.update(step_data.get("files_checked", []))
+        self.consolidated_findings.relevant_files.update(step_data.get("relevant_files", []))
+        self.consolidated_findings.relevant_context.update(step_data.get("relevant_context", []))
+        self.consolidated_findings.findings.append(f"Step {step_data['step_number']}: {step_data['findings']}")
+        if step_data.get("hypothesis"):
+            self.consolidated_findings.hypotheses.append(
+                {
+                    "step": step_data["step_number"],
+                    "hypothesis": step_data["hypothesis"],
+                    "confidence": step_data["confidence"],
+                }
+            )
+        if step_data.get("issues_found"):
+            self.consolidated_findings.issues_found.extend(step_data["issues_found"])
+        if step_data.get("images"):
+            self.consolidated_findings.images.extend(step_data["images"])
+        # Update confidence to latest value from this step
+        if step_data.get("confidence"):
+            self.consolidated_findings.confidence = step_data["confidence"]
+
+    def _reprocess_consolidated_findings(self):
+        """Reprocess consolidated findings after backtracking"""
+        self.consolidated_findings = ConsolidatedFindings()
+        for step in self.work_history:
+            self._update_consolidated_findings(step)
+
+    def _prepare_work_summary(self) -> str:
+        """Prepare a comprehensive summary of the work"""
+        summary_parts = [
+            f"=== {self.get_name().upper()} WORK SUMMARY ===",
+            f"Total steps: {len(self.work_history)}",
+            f"Files examined: {len(self.consolidated_findings.files_checked)}",
+            f"Relevant files identified: {len(self.consolidated_findings.relevant_files)}",
+            f"Methods/functions involved: {len(self.consolidated_findings.relevant_context)}",
+            f"Issues found: {len(self.consolidated_findings.issues_found)}",
+            "",
+            "=== WORK PROGRESSION ===",
+        ]
+
+        for finding in self.consolidated_findings.findings:
+            summary_parts.append(finding)
+
+        if self.consolidated_findings.hypotheses:
+            summary_parts.extend(
+                [
+                    "",
+                    "=== HYPOTHESIS EVOLUTION ===",
+                ]
+            )
+            for hyp in self.consolidated_findings.hypotheses:
+                summary_parts.append(f"Step {hyp['step']} ({hyp['confidence']} confidence): {hyp['hypothesis']}")
+
+        if self.consolidated_findings.issues_found:
+            summary_parts.extend(
+                [
+                    "",
+                    "=== ISSUES IDENTIFIED ===",
+                ]
+            )
+            for issue in self.consolidated_findings.issues_found:
+                severity = issue.get("severity", "unknown")
+                description = issue.get("description", "No description")
+                summary_parts.append(f"[{severity.upper()}] {description}")
+
+        return "\n".join(summary_parts)
+
+    def get_expert_initial_request(self, initial: Optional[str], fallback: str) -> str:
+        """Reference an identical current step without duplicating required input."""
+        description = initial or fallback
+        if description == self._current_arguments.get("step"):
+            return "See the current caller step supplied above."
+        return description
+
+    async def _call_expert_analysis(self, arguments: dict, request) -> dict:
+        """Launch one final advisory analysis, preserving caller-controlled workflow gates."""
+        try:
+            files = self._resolve_cli_target(
+                request,
+                files=tuple(sorted(self.consolidated_findings.relevant_files)),
+                images=tuple(dict.fromkeys(self.consolidated_findings.images)),
+            )
+            self.consolidated_findings.relevant_files = set(files)
+            context = self.prepare_expert_analysis_context(self.consolidated_findings)
+            instruction = self.get_expert_analysis_instruction()
+            prompt = (
+                f"=== CURRENT CALLER STEP ===\n{request.step}\n=== END CURRENT CALLER STEP ===\n\n"
+                f"=== INVESTIGATION DATA ===\n{context}\n=== END INVESTIGATION DATA ===\n\n{instruction}"
+            )
+            result = await self._run_cli(
+                request,
+                prompt,
+                self.get_system_prompt() + "\n\n" + self.get_language_instruction(),
+                files=tuple(sorted(self.consolidated_findings.relevant_files)),
+                images=tuple(dict.fromkeys(self.consolidated_findings.images)),
+            )
+            content = result.content.strip()
+            match = re.fullmatch(r"```(?:json)?\s*(.*?)\s*```", content, re.DOTALL)
+            if match:
+                content = match.group(1).strip()
+            try:
+                analysis = json.loads(content)
+            except json.JSONDecodeError:
+                analysis = None
+            if isinstance(analysis, dict):
+                return analysis
+            return {"status": "analysis_complete", "raw_analysis": result.content, "format": "text"}
+        except BackendError as exc:
+            return {"status": "analysis_error", "error": str(exc), "metadata": exc.to_dict()}
+
+    def _process_work_step(self, step_data: dict):
+        """
+        Process a single work step and update internal state.
+
+        This method is useful for testing and manual step processing.
+        It adds the step to work history and updates consolidated findings.
+
+        Args:
+            step_data: Dictionary containing step information including:
+                      step, step_number, findings, files_checked, etc.
+        """
+        # Store in history
+        self.work_history.append(step_data)
+
+        # Update consolidated findings
+        self._update_consolidated_findings(step_data)
+
+    # Common execute method for workflow-based tools
+
+    async def execute(self, arguments: dict[str, Any]) -> list[TextContent]:
+        """
+        Common execute logic for workflow-based tools.
+
+        This method provides common validation and delegates to execute_workflow.
+        Tools that need custom execute logic can override this method.
+        """
+        try:
+            # Common validation
+            if not arguments:
+                error_data = {"status": "error", "content": "No arguments provided"}
+                # Add basic metadata even for validation errors
+                error_data["metadata"] = {"tool_name": self.get_name()}
+                raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False))
+
+            # Delegate to execute_workflow
+            return await self.execute_workflow(arguments)
+
+        except (ToolExecutionError, StateError):
+            raise
+        except BackendError as exc:
+            error_data = {"status": "error", "content": str(exc), "metadata": exc.to_dict()}
+            raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from None
+        except Exception as exc:
+            logger.error("workflow_execution_failed tool=%s error_type=%s", self.get_name(), type(exc).__name__)
+            error_data = {
+                "status": "error",
+                "content": "The workflow could not complete this request.",
+                "metadata": {"code": "tool_error", "tool_name": self.get_name(), "error_type": type(exc).__name__},
+            }
+            raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from None
+
+    # Default implementations for methods that workflow-based tools typically don't need
+
+    async def prepare_prompt(self, request) -> str:
+        """
+        Base implementation for workflow tools - compatible with BaseTool signature.
+
+        Workflow tools typically don't need to return a prompt since they handle
+        their own prompt preparation internally through the workflow execution.
+
+        Args:
+            request: The validated request object
+
+        Returns:
+            Empty string since workflow tools manage prompts internally
+        """
+        # Workflow tools handle their prompts internally during workflow execution
+        return ""
+
+    def format_response(self, response: str, request, model_info=None):
+        """
+        Workflow tools handle their own response formatting.
+        The BaseWorkflowMixin formats responses internally.
+        """
+        return response