gobby 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

gobby/workflows/enforcement/blocking.py

@@ -0,0 +1,269 @@
+"""Tool blocking enforcement for workflow engine.
+
+Provides configurable tool blocking based on workflow state and conditions.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from gobby.workflows.git_utils import get_dirty_files
+from gobby.workflows.safe_evaluator import LazyBool, SafeExpressionEvaluator
+
+if TYPE_CHECKING:
+    from gobby.storage.tasks import LocalTaskManager
+    from gobby.workflows.definitions import WorkflowState
+
+logger = logging.getLogger(__name__)
+
+
+def _is_plan_file(file_path: str, source: str | None = None) -> bool:
+    """Check if file path is a Claude Code plan file (platform-agnostic).
+
+    Only exempts plan files for Claude Code sessions to avoid accidental
+    exemptions for Gemini/Codex users.
+
+    The pattern `/.claude/plans/` matches paths like:
+    - Unix: /Users/xxx/.claude/plans/file.md  (the / comes from xxx/)
+    - Windows: C:/Users/xxx/.claude/plans/file.md  (after normalization)
+
+    Args:
+        file_path: The file path being edited
+        source: CLI source (e.g., "claude", "gemini", "codex")
+
+    Returns:
+        True if this is a CC plan file that should be exempt from task requirement
+    """
+    if not file_path:
+        return False
+    # Only exempt for Claude Code sessions
+    if source != "claude":
+        return False
+    # Normalize path separators (Windows backslash to forward slash)
+    normalized = file_path.replace("\\", "/")
+    return "/.claude/plans/" in normalized
+
+
+def _evaluate_block_condition(
+    condition: str | None,
+    workflow_state: WorkflowState | None,
+    event_data: dict[str, Any] | None = None,
+    tool_input: dict[str, Any] | None = None,
+    session_has_dirty_files: LazyBool | bool = False,
+    task_has_commits: LazyBool | bool = False,
+    source: str | None = None,
+) -> bool:
+    """
+    Evaluate a blocking rule condition against workflow state.
+
+    Supports simple Python expressions with access to:
+    - variables: workflow state variables dict
+    - task_claimed: shorthand for variables.get('task_claimed')
+    - plan_mode: shorthand for variables.get('plan_mode')
+    - tool_input: the tool's input arguments (for MCP tool checks)
+    - session_has_dirty_files: whether session has NEW dirty files (beyond baseline)
+    - task_has_commits: whether the current task has linked commits
+    - source: CLI source (e.g., "claude", "gemini", "codex")
+
+    Args:
+        condition: Python expression to evaluate
+        workflow_state: Current workflow state
+        event_data: Optional hook event data
+        tool_input: Tool input arguments (for MCP tools, this is the 'arguments' field)
+        session_has_dirty_files: Whether session has dirty files beyond baseline (lazy or bool)
+        task_has_commits: Whether claimed task has linked commits (lazy or bool)
+        source: CLI source identifier
+
+    Returns:
+        True if condition matches (tool should be blocked), False otherwise.
+    """
+    if not condition:
+        return True  # No condition means always match
+
+    # Build evaluation context
+    variables = workflow_state.variables if workflow_state else {}
+    context = {
+        "variables": variables,
+        "task_claimed": variables.get("task_claimed", False),
+        "plan_mode": variables.get("plan_mode", False),
+        "event": event_data or {},
+        "tool_input": tool_input or {},
+        "session_has_dirty_files": session_has_dirty_files,
+        "task_has_commits": task_has_commits,
+        "source": source or "",
+    }
+
+    # Allowed functions for safe evaluation
+    allowed_funcs: dict[str, Callable[..., Any]] = {
+        "is_plan_file": _is_plan_file,
+        "bool": bool,
+        "str": str,
+        "int": int,
+    }
+
+    try:
+        evaluator = SafeExpressionEvaluator(context, allowed_funcs)
+        return evaluator.evaluate(condition)
+    except Exception as e:
+        # Fail-closed: block the tool if condition evaluation fails to prevent bypass
+        logger.error(
+            f"block_tools condition evaluation failed (blocking tool): condition='{condition}', "
+            f"variables={variables}, error={e}",
+            exc_info=True,
+        )
+        return True
+
+
+async def block_tools(
+    rules: list[dict[str, Any]] | None = None,
+    event_data: dict[str, Any] | None = None,
+    workflow_state: WorkflowState | None = None,
+    project_path: str | None = None,
+    task_manager: LocalTaskManager | None = None,
+    source: str | None = None,
+    **kwargs: Any,
+) -> dict[str, Any] | None:
+    """
+    Unified tool blocking with multiple configurable rules.
+
+    Each rule can specify:
+      - tools: List of tool names to block (for native CC tools)
+      - mcp_tools: List of "server:tool" patterns to block (for MCP tools)
+      - when: Optional condition (evaluated against workflow state)
+      - reason: Block message to display
+
+    For MCP tools, the tool_name in event_data is "call_tool" or "mcp__gobby__call_tool",
+    and we look inside tool_input for server_name and tool_name.
+
+    Condition evaluation has access to:
+      - variables: workflow state variables
+      - task_claimed, plan_mode: shortcuts
+      - tool_input: the MCP tool's arguments (for checking commit_sha etc.)
+      - session_has_dirty_files: whether session has NEW dirty files beyond baseline
+      - task_has_commits: whether the claimed task has linked commits
+      - source: CLI source (e.g., "claude", "gemini", "codex")
+
+    Args:
+        rules: List of blocking rules
+        event_data: Hook event data with tool_name, tool_input
+        workflow_state: For evaluating conditions
+        project_path: Path to project for git status checks
+        task_manager: For checking task commit status
+        source: CLI source identifier (for is_plan_file checks)
+
+    Returns:
+        Dict with decision="block" and reason if blocked, None to allow.
+
+    Example rule (native tools):
+        {
+            "tools": ["TaskCreate", "TaskUpdate"],
+            "reason": "CC native task tools are disabled. Use gobby-tasks MCP tools."
+        }
+
+    Example rule with condition:
+        {
+            "tools": ["Edit", "Write", "NotebookEdit"],
+            "when": "not task_claimed and not plan_mode",
+            "reason": "Claim a task before using Edit, Write, or NotebookEdit tools."
+        }
+
+    Example rule (MCP tools):
+        {
+            "mcp_tools": ["gobby-tasks:close_task"],
+            "when": "not task_has_commits and not tool_input.get('commit_sha')",
+            "reason": "A commit is required before closing this task."
+        }
+    """
+    if not event_data or not rules:
+        return None
+
+    tool_name = event_data.get("tool_name")
+    if not tool_name:
+        return None
+
+    tool_input = event_data.get("tool_input", {}) or {}
+
+    # Create lazy thunks for expensive context values (git status, DB queries).
+    # These are only evaluated when actually referenced in a rule condition.
+
+    def _compute_session_has_dirty_files() -> bool:
+        """Lazy thunk: check for new dirty files beyond baseline."""
+        if not workflow_state:
+            return False
+        if project_path is None:
+            # Can't compute without project_path - avoid running git in wrong directory
+            logger.debug("_compute_session_has_dirty_files: project_path is None, returning False")
+            return False
+        baseline_dirty = set(workflow_state.variables.get("baseline_dirty_files", []))
+        current_dirty = get_dirty_files(project_path)
+        new_dirty = current_dirty - baseline_dirty
+        return len(new_dirty) > 0
+
+    def _compute_task_has_commits() -> bool:
+        """Lazy thunk: check if claimed task has linked commits."""
+        if not workflow_state or not task_manager:
+            return False
+        claimed_task_id = workflow_state.variables.get("claimed_task_id")
+        if not claimed_task_id:
+            return False
+        try:
+            task = task_manager.get_task(claimed_task_id)
+            return bool(task and task.commits)
+        except Exception:
+            return False  # nosec B110 - best-effort check
+
+    # Wrap in LazyBool so they're only computed when used in boolean context
+    session_has_dirty_files: LazyBool | bool = LazyBool(_compute_session_has_dirty_files)
+    task_has_commits: LazyBool | bool = LazyBool(_compute_task_has_commits)
+
+    for rule in rules:
+        # Determine if this rule matches the current tool
+        rule_matches = False
+        mcp_tool_args: dict[str, Any] = {}
+
+        # Check native CC tools (Edit, Write, etc.)
+        if "tools" in rule:
+            tools = rule.get("tools", [])
+            if tool_name in tools:
+                rule_matches = True
+
+        # Check MCP tools (server:tool format)
+        elif "mcp_tools" in rule:
+            # MCP calls come in as "call_tool" or "mcp__gobby__call_tool"
+            if tool_name in ("call_tool", "mcp__gobby__call_tool"):
+                mcp_server = tool_input.get("server_name", "")
+                mcp_tool = tool_input.get("tool_name", "")
+                mcp_key = f"{mcp_server}:{mcp_tool}"
+
+                mcp_tools = rule.get("mcp_tools", [])
+                if mcp_key in mcp_tools:
+                    rule_matches = True
+                    # For MCP tools, the actual arguments are in tool_input.arguments
+                    mcp_tool_args = tool_input.get("arguments", {}) or {}
+
+        if not rule_matches:
+            continue
+
+        # Check optional condition
+        condition = rule.get("when")
+        if condition:
+            # For MCP tools, use the nested arguments for condition evaluation
+            eval_tool_input = mcp_tool_args if mcp_tool_args else tool_input
+            if not _evaluate_block_condition(
+                condition,
+                workflow_state,
+                event_data,
+                tool_input=eval_tool_input,
+                session_has_dirty_files=session_has_dirty_files,
+                task_has_commits=task_has_commits,
+                source=source,
+            ):
+                continue
+
+        reason = rule.get("reason", f"Tool '{tool_name}' is blocked.")
+        logger.info(f"block_tools: Blocking '{tool_name}' - {reason[:100]}")
+        return {"decision": "block", "reason": reason}
+
+    return None

gobby/workflows/enforcement/commit_policy.py

@@ -0,0 +1,283 @@
+"""Commit policy enforcement for workflow engine.
+
+Provides actions that enforce commit requirements before stopping or closing tasks.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from gobby.workflows.git_utils import get_dirty_files
+
+if TYPE_CHECKING:
+    from gobby.storage.tasks import LocalTaskManager
+    from gobby.workflows.definitions import WorkflowState
+
+logger = logging.getLogger(__name__)
+
+
+async def capture_baseline_dirty_files(
+    workflow_state: WorkflowState | None,
+    project_path: str | None = None,
+) -> dict[str, Any] | None:
+    """
+    Capture current dirty files as baseline for session-aware detection.
+
+    Called on session_start to record pre-existing dirty files. The
+    require_commit_before_stop action will compare against this baseline
+    to detect only NEW dirty files made during the session.
+
+    Args:
+        workflow_state: Workflow state to store baseline in
+        project_path: Path to the project directory for git status check
+
+    Returns:
+        Dict with captured baseline info, or None if no workflow_state
+    """
+    if not workflow_state:
+        logger.debug("capture_baseline_dirty_files: No workflow_state, skipping")
+        return None
+
+    dirty_files = get_dirty_files(project_path)
+
+    # Store as a list in workflow state (sets aren't JSON serializable)
+    workflow_state.variables["baseline_dirty_files"] = list(dirty_files)
+
+    # Log for debugging baseline capture issues
+    files_preview = list(dirty_files)[:5]
+    logger.info(
+        f"capture_baseline_dirty_files: project_path={project_path}, "
+        f"captured {len(dirty_files)} files: {files_preview}"
+    )
+
+    return {
+        "baseline_captured": True,
+        "file_count": len(dirty_files),
+        "files": list(dirty_files),
+    }
+
+
+async def require_commit_before_stop(
+    workflow_state: WorkflowState | None,
+    project_path: str | None = None,
+    task_manager: LocalTaskManager | None = None,
+) -> dict[str, Any] | None:
+    """
+    Block stop if there's an in_progress task with uncommitted changes.
+
+    This action is designed for on_stop triggers to enforce that agents
+    commit their work and close tasks before stopping.
+
+    Args:
+        workflow_state: Workflow state with variables (claimed_task_id, etc.)
+        project_path: Path to the project directory for git status check
+        task_manager: LocalTaskManager to verify task status
+
+    Returns:
+        Dict with decision="block" and reason if task has uncommitted changes,
+        or None to allow the stop.
+    """
+    if not workflow_state:
+        logger.debug("require_commit_before_stop: No workflow_state, allowing")
+        return None
+
+    claimed_task_id = workflow_state.variables.get("claimed_task_id")
+    if not claimed_task_id:
+        logger.debug("require_commit_before_stop: No claimed task, allowing")
+        return None
+
+    # Verify the task is actually still in_progress (not just cached in workflow state)
+    if task_manager:
+        task = task_manager.get_task(claimed_task_id)
+        if not task or task.status != "in_progress":
+            # Task was changed - clear the stale workflow state
+            logger.debug(
+                f"require_commit_before_stop: Task '{claimed_task_id}' is no longer "
+                f"in_progress (status={task.status if task else 'not found'}), clearing state"
+            )
+            workflow_state.variables["claimed_task_id"] = None
+            workflow_state.variables["task_claimed"] = False
+            return None
+
+    # Check for uncommitted changes using baseline-aware comparison
+    current_dirty = get_dirty_files(project_path)
+
+    if not current_dirty:
+        logger.debug("require_commit_before_stop: No uncommitted changes, allowing")
+        return None
+
+    # Get baseline dirty files captured at session start
+    baseline_dirty = set(workflow_state.variables.get("baseline_dirty_files", []))
+
+    # Calculate NEW dirty files (not in baseline)
+    new_dirty = current_dirty - baseline_dirty
+
+    if not new_dirty:
+        logger.debug(
+            f"require_commit_before_stop: All {len(current_dirty)} dirty files were pre-existing "
+            f"(in baseline), allowing"
+        )
+        return None
+
+    logger.debug(
+        f"require_commit_before_stop: Found {len(new_dirty)} new dirty files "
+        f"(baseline had {len(baseline_dirty)}, current has {len(current_dirty)})"
+    )
+
+    # Track how many times we've blocked to prevent infinite loops
+    block_count = workflow_state.variables.get("_commit_block_count", 0)
+    if block_count >= 3:
+        logger.warning(
+            f"require_commit_before_stop: Reached max block count ({block_count}), allowing"
+        )
+        return None
+
+    workflow_state.variables["_commit_block_count"] = block_count + 1
+
+    # Block - agent needs to commit and close
+    logger.info(
+        f"require_commit_before_stop: Blocking stop - task '{claimed_task_id}' "
+        f"has {len(new_dirty)} uncommitted changes"
+    )
+
+    # Build list of new dirty files for the message (limit to 10 for readability)
+    new_dirty_list = sorted(new_dirty)[:10]
+    files_display = "\n".join(f"  - {f}" for f in new_dirty_list)
+    if len(new_dirty) > 10:
+        files_display += f"\n  ... and {len(new_dirty) - 10} more files"
+
+    return {
+        "decision": "block",
+        "reason": (
+            f"Task '{claimed_task_id}' is in_progress with {len(new_dirty)} uncommitted "
+            f"changes made during this session:\n{files_display}\n\n"
+            f"Before stopping, commit your changes and close the task:\n"
+            f"1. Commit with [{claimed_task_id}] in the message\n"
+            f'2. Close the task: close_task(task_id="{claimed_task_id}", commit_sha="...")'
+        ),
+    }
+
+
+async def require_task_review_or_close_before_stop(
+    workflow_state: WorkflowState | None,
+    task_manager: LocalTaskManager | None = None,
+    project_id: str | None = None,
+    **kwargs: Any,
+) -> dict[str, Any] | None:
+    """Block stop if session has an in_progress task.
+
+    Agents must close their task (or send to review) before stopping.
+    The close_task() validation already requires a commit, so we don't
+    need to check for uncommitted changes here - that's handled by
+    require_commit_before_stop if needed.
+
+    Checks both:
+    1. claimed_task_id - task explicitly claimed via update_task(status="in_progress")
+    2. session_task - task(s) assigned via set_variable (fallback if no claimed_task_id)
+
+    Args:
+        workflow_state: Workflow state with variables (claimed_task_id, etc.)
+        task_manager: LocalTaskManager to verify task status
+        project_id: Project ID for resolving task references (#N, N formats)
+        **kwargs: Accepts additional kwargs for compatibility
+
+    Returns:
+        Dict with decision="block" and reason if task is still in_progress,
+        or None to allow the stop.
+    """
+    if not workflow_state:
+        logger.debug("require_task_review_or_close_before_stop: No workflow_state, allowing")
+        return None
+
+    # 1. Check claimed_task_id first (existing behavior)
+    claimed_task_id = workflow_state.variables.get("claimed_task_id")
+
+    # 2. If no claimed task, fall back to session_task
+    if not claimed_task_id and task_manager:
+        session_task = workflow_state.variables.get("session_task")
+        if session_task and session_task != "*":
+            # Normalize to list
+            task_ids = [session_task] if isinstance(session_task, str) else session_task
+
+            if isinstance(task_ids, list):
+                for task_id in task_ids:
+                    try:
+                        task = task_manager.get_task(task_id, project_id=project_id)
+                    except ValueError:
+                        continue
+                    if task and task.status == "in_progress":
+                        claimed_task_id = task_id
+                        logger.debug(
+                            f"require_task_review_or_close_before_stop: Found in_progress "
+                            f"session_task '{task_id}'"
+                        )
+                        break
+                    # Also check subtasks
+                    if task:
+                        subtasks = task_manager.list_tasks(parent_task_id=task.id)
+                        for subtask in subtasks:
+                            if subtask.status == "in_progress":
+                                claimed_task_id = subtask.id
+                                logger.debug(
+                                    f"require_task_review_or_close_before_stop: Found in_progress "
+                                    f"subtask '{subtask.id}' under session_task '{task_id}'"
+                                )
+                                break
+                    if claimed_task_id:
+                        break
+
+    if not claimed_task_id:
+        logger.debug("require_task_review_or_close_before_stop: No claimed task, allowing")
+        return None
+
+    if not task_manager:
+        logger.debug("require_task_review_or_close_before_stop: No task_manager, allowing")
+        return None
+
+    try:
+        task = task_manager.get_task(claimed_task_id, project_id=project_id)
+        if not task:
+            # Task not found - clear stale workflow state and allow
+            logger.debug(
+                f"require_task_review_or_close_before_stop: Task '{claimed_task_id}' not found, "
+                f"clearing state"
+            )
+            workflow_state.variables["claimed_task_id"] = None
+            workflow_state.variables["task_claimed"] = False
+            return None
+
+        if task.status != "in_progress":
+            # Task is closed or in review - allow stop
+            logger.debug(
+                f"require_task_review_or_close_before_stop: Task '{claimed_task_id}' "
+                f"status={task.status}, allowing"
+            )
+            # Clear stale workflow state
+            workflow_state.variables["claimed_task_id"] = None
+            workflow_state.variables["task_claimed"] = False
+            return None
+
+        # Task is still in_progress - block the stop
+        task_ref = f"#{task.seq_num}" if task.seq_num else task.id[:8]
+        logger.info(
+            f"require_task_review_or_close_before_stop: Blocking stop - task "
+            f"{task_ref} is still in_progress"
+        )
+
+        return {
+            "decision": "block",
+            "reason": (
+                f"\nTask {task_ref} is still in_progress. "
+                f"Close it with close_task() before stopping."
+            ),
+            "task_id": claimed_task_id,
+            "task_status": task.status,
+        }
+
+    except Exception as e:
+        logger.warning(
+            f"require_task_review_or_close_before_stop: Failed to check task status: {e}"
+        )
+        # Allow stop if we can't check - don't block on errors
+        return None