gobby 0.2.8__py3-none-any.whl → 0.2.11__py3-none-any.whl

gobby/workflows/detection_helpers.py

@@ -103,30 +103,42 @@ def detect_task_claim(
         if isinstance(result, dict) and result.get("error"):
             return
 
-    # Extract task_id based on tool type
+    # Extract task_id based on tool type - MUST resolve to UUID
+    # Refs like '#123' will fail comparison with task.id (UUID) in close_task logic
     arguments = tool_input.get("arguments", {}) or {}
+    task_id: str | None = None
+
     if inner_tool_name in ("update_task", "claim_task"):
-        task_id = arguments.get("task_id")
-        # Resolve to UUID for consistent comparison with close_task
-        if task_id and task_manager:
+        raw_task_id = arguments.get("task_id")
+        # MUST resolve to UUID - refs like '#123' break comparisons in close_task
+        if raw_task_id and task_manager:
             try:
-                task = task_manager.get_task(task_id)
+                task = task_manager.get_task(raw_task_id)
                 if task:
                     task_id = task.id  # Use UUID
-            except Exception:  # nosec B110 - best effort resolution, keep original if fails
-                pass
+                else:
+                    logger.warning(
+                        f"Cannot resolve task ref '{raw_task_id}' to UUID - task not found"
+                    )
+            except Exception as e:
+                logger.warning(f"Cannot resolve task ref '{raw_task_id}' to UUID: {e}")
+        elif raw_task_id and not task_manager:
+            logger.warning(f"Cannot resolve task ref '{raw_task_id}' to UUID - no task_manager")
     elif inner_tool_name == "create_task":
-        # For create_task, the id is in the result
+        # For create_task, the id is in the result (already a UUID)
         result = tool_output.get("result", {}) if isinstance(tool_output, dict) else {}
         task_id = result.get("id") if isinstance(result, dict) else None
         # Skip if we can't get the task ID (e.g., Claude Code doesn't include tool results)
         # The MCP tool itself handles state updates in this case via _crud.py
         if not task_id:
             return
-    else:
-        task_id = None
 
-    # All conditions met - set task_claimed and claimed_task_id
+    # Only set claimed_task_id if we have a valid UUID
+    if not task_id:
+        logger.debug(f"Skipping task claim state update - no valid UUID for {inner_tool_name}")
+        return
+
+    # All conditions met - set task_claimed and claimed_task_id (UUID)
     state.variables["task_claimed"] = True
     state.variables["claimed_task_id"] = task_id
     logger.info(

gobby/workflows/enforcement/__init__.py

@@ -4,7 +4,12 @@ This package provides actions that enforce task tracking before allowing
 certain tools, and enforce task completion before allowing agent to stop.
 """
 
-from gobby.workflows.enforcement.blocking import block_tools
+from gobby.workflows.enforcement.blocking import (
+    block_tools,
+    is_discovery_tool,
+    is_tool_unlocked,
+    track_schema_lookup,
+)
 from gobby.workflows.enforcement.commit_policy import (
     capture_baseline_dirty_files,
     require_commit_before_stop,
@@ -17,6 +22,7 @@ from gobby.workflows.enforcement.handlers import (
     handle_require_commit_before_stop,
     handle_require_task_complete,
     handle_require_task_review_or_close_before_stop,
+    handle_track_schema_lookup,
     handle_validate_session_task_scope,
 )
 from gobby.workflows.enforcement.task_policy import (
@@ -28,6 +34,9 @@ from gobby.workflows.enforcement.task_policy import (
 __all__ = [
     # Blocking
     "block_tools",
+    "is_discovery_tool",
+    "is_tool_unlocked",
+    "track_schema_lookup",
     # Commit policy
     "capture_baseline_dirty_files",
     "require_commit_before_stop",
@@ -43,5 +52,6 @@ __all__ = [
     "handle_require_commit_before_stop",
     "handle_require_task_complete",
     "handle_require_task_review_or_close_before_stop",
+    "handle_track_schema_lookup",
     "handle_validate_session_task_scope",
 ]

gobby/workflows/enforcement/blocking.py

@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING, Any
 
 from gobby.workflows.git_utils import get_dirty_files
 from gobby.workflows.safe_evaluator import LazyBool, SafeExpressionEvaluator
+from gobby.workflows.templates import TemplateEngine
 
 if TYPE_CHECKING:
     from gobby.storage.tasks import LocalTaskManager
@@ -19,6 +20,89 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+# MCP discovery tools that don't require prior schema lookup
+DISCOVERY_TOOLS = {
+    "list_mcp_servers",
+    "list_tools",
+    "get_tool_schema",
+    "search_tools",
+    "recommend_tools",
+    "list_skills",
+    "get_skill",
+    "search_skills",
+}
+
+
+def is_discovery_tool(tool_name: str | None) -> bool:
+    """Check if the tool is a discovery/introspection tool.
+
+    These tools are allowed without prior schema lookup since they ARE
+    the discovery mechanism.
+
+    Args:
+        tool_name: The MCP tool name (from tool_input.tool_name)
+
+    Returns:
+        True if this is a discovery tool that doesn't need schema unlock
+    """
+    return tool_name in DISCOVERY_TOOLS if tool_name else False
+
+
+def is_tool_unlocked(
+    tool_input: dict[str, Any],
+    variables: dict[str, Any],
+) -> bool:
+    """Check if a tool has been unlocked via prior get_tool_schema call.
+
+    Args:
+        tool_input: The tool input containing server_name and tool_name
+        variables: Workflow state variables containing unlocked_tools list
+
+    Returns:
+        True if the server:tool combo was previously unlocked via get_tool_schema
+    """
+    server = tool_input.get("server_name", "")
+    tool = tool_input.get("tool_name", "")
+    if not server or not tool:
+        return False
+    key = f"{server}:{tool}"
+    unlocked = variables.get("unlocked_tools", [])
+    return key in unlocked
+
+
+def track_schema_lookup(
+    tool_input: dict[str, Any],
+    workflow_state: WorkflowState | None,
+) -> dict[str, Any] | None:
+    """Track a successful get_tool_schema call by adding to unlocked_tools.
+
+    Called from on_after_tool when tool_name is get_tool_schema and succeeded.
+
+    Args:
+        tool_input: The tool input containing server_name and tool_name
+        workflow_state: Workflow state to update
+
+    Returns:
+        Dict with tracking result or None
+    """
+    if not workflow_state:
+        return None
+
+    server = tool_input.get("server_name", "")
+    tool = tool_input.get("tool_name", "")
+    if not server or not tool:
+        return None
+
+    key = f"{server}:{tool}"
+    unlocked = workflow_state.variables.setdefault("unlocked_tools", [])
+
+    if key not in unlocked:
+        unlocked.append(key)
+        logger.debug(f"Unlocked tool schema: {key}")
+        return {"unlocked": key, "total_unlocked": len(unlocked)}
+
+    return {"already_unlocked": key}
+
 
 def _is_plan_file(file_path: str, source: str | None = None) -> bool:
     """Check if file path is a Claude Code plan file (platform-agnostic).
@@ -99,6 +183,8 @@ def _evaluate_block_condition(
     # Allowed functions for safe evaluation
     allowed_funcs: dict[str, Callable[..., Any]] = {
         "is_plan_file": _is_plan_file,
+        "is_discovery_tool": is_discovery_tool,
+        "is_tool_unlocked": lambda ti: is_tool_unlocked(ti, variables),
         "bool": bool,
         "str": str,
         "int": int,
@@ -275,6 +361,16 @@ async def block_tools(
                 continue
 
         reason = rule.get("reason", f"Tool '{tool_name}' is blocked.")
+
+        # Render Jinja2 template variables in reason message
+        if "{{" in reason:
+            try:
+                engine = TemplateEngine()
+                reason = engine.render(reason, {"tool_input": tool_input})
+            except Exception as e:
+                logger.warning(f"Failed to render reason template: {e}")
+                # Keep original reason on failure
+
         logger.info(f"block_tools: Blocking '{tool_name}' - {reason[:100]}")
         return {"decision": "block", "reason": reason}
 

gobby/workflows/enforcement/handlers.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Any
 
-from gobby.workflows.enforcement.blocking import block_tools
+from gobby.workflows.enforcement.blocking import block_tools, track_schema_lookup
 from gobby.workflows.enforcement.commit_policy import (
     capture_baseline_dirty_files,
     require_commit_before_stop,
@@ -33,6 +33,7 @@ __all__ = [
     "handle_require_commit_before_stop",
     "handle_require_task_complete",
     "handle_require_task_review_or_close_before_stop",
+    "handle_track_schema_lookup",
     "handle_validate_session_task_scope",
 ]
 
@@ -267,3 +268,36 @@ async def handle_require_task_complete(
         project_id=project_id,
         workflow_state=context.state,
     )
+
+
+async def handle_track_schema_lookup(
+    context: Any,
+    task_manager: LocalTaskManager | None = None,
+    **kwargs: Any,
+) -> dict[str, Any] | None:
+    """ActionHandler wrapper for track_schema_lookup.
+
+    Tracks successful get_tool_schema calls to unlock tools for call_tool.
+    Should be triggered on on_after_tool when the tool is get_tool_schema.
+    """
+    if not context.event_data:
+        return None
+
+    tool_name = context.event_data.get("tool_name", "")
+    is_failure = context.event_data.get("is_failure", False)
+
+    # Only track successful get_tool_schema calls
+    # Handle both native MCP format and Gobby proxy format
+    if tool_name not in ("get_tool_schema", "mcp__gobby__get_tool_schema"):
+        return None
+
+    if is_failure:
+        return None
+
+    # Extract tool_input - for MCP proxy, it's in tool_input directly
+    tool_input = context.event_data.get("tool_input", {}) or {}
+
+    return track_schema_lookup(
+        tool_input=tool_input,
+        workflow_state=context.state,
+    )

gobby/workflows/enforcement/task_policy.py

@@ -6,6 +6,7 @@ Provides actions that enforce task tracking and scoping requirements.
 from __future__ import annotations
 
 import logging
+import uuid
 from typing import TYPE_CHECKING, Any
 
 from gobby.mcp_proxy.tools.task_readiness import is_descendant_of
@@ -21,6 +22,15 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _is_uuid(value: str) -> bool:
+    """Check if a string is a valid UUID (not a ref like #123)."""
+    try:
+        uuid.UUID(value)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
 async def require_task_complete(
     task_manager: LocalTaskManager | None,
     session_id: str,
@@ -84,6 +94,14 @@ async def require_task_complete(
     if workflow_state:
         has_claimed_task = workflow_state.variables.get("task_claimed", False)
         claimed_task_id = workflow_state.variables.get("claimed_task_id")
+        # Resolve claimed_task_id to UUID if it's a ref (backward compat)
+        if claimed_task_id and not _is_uuid(claimed_task_id):
+            try:
+                claimed_task = task_manager.get_task(claimed_task_id)
+                if claimed_task:
+                    claimed_task_id = claimed_task.id
+            except Exception:  # nosec B110 - keep original ID if resolution fails
+                claimed_task_id = claimed_task_id  # explicit no-op
 
     try:
         # Collect incomplete tasks across all specified task IDs

gobby/workflows/engine.py

@@ -116,7 +116,11 @@ class WorkflowEngine:
                 if state.step != "reflect":
                     project_path = Path(event.cwd) if event.cwd else None
                     workflow = self.loader.load_workflow(state.workflow_name, project_path)
-                    if workflow and workflow.get_step("reflect"):
+                    if (
+                        workflow
+                        and isinstance(workflow, WorkflowDefinition)
+                        and workflow.get_step("reflect")
+                    ):
                         await self.transition_to(state, "reflect", workflow)
                         return HookResponse(
                             decision="modify",
@@ -145,6 +149,11 @@ class WorkflowEngine:
             )
             return HookResponse(decision="allow")
 
+        # Step handling only applies to WorkflowDefinition, not PipelineDefinition
+        if not isinstance(workflow, WorkflowDefinition):
+            logger.debug(f"Workflow '{workflow.name}' is a pipeline, skipping step handling")
+            return HookResponse(decision="allow")
+
         # 4. Process event
         # Logic matches WORKFLOWS.md "Evaluation Flow"
 
@@ -344,6 +353,8 @@ class WorkflowEngine:
             memory_sync_manager=self.action_executor.memory_sync_manager,
             task_sync_manager=self.action_executor.task_sync_manager,
             session_task_manager=self.action_executor.session_task_manager,
+            pipeline_executor=self.action_executor.pipeline_executor,
+            workflow_loader=self.action_executor.workflow_loader,
         )
 
         for action_def in actions:
@@ -530,6 +541,14 @@ class WorkflowEngine:
                 "error": f"Workflow '{workflow_name}' is lifecycle type (auto-runs on events)",
             }
 
+        # Only WorkflowDefinition can be activated as step workflows
+        if not isinstance(definition, WorkflowDefinition):
+            logger.debug(f"Workflow '{workflow_name}' is a pipeline, not a step workflow")
+            return {
+                "success": False,
+                "error": f"'{workflow_name}' is a pipeline. Use pipeline execution instead.",
+            }
+
         # Check for existing step workflow
         existing = self.state_manager.get_state(session_id)
         if existing and existing.workflow_name != "__lifecycle__":
@@ -553,10 +572,13 @@ class WorkflowEngine:
             }
         step = definition.steps[0].name
 
-        # Merge workflow default variables with passed-in variables
-        merged_variables = dict(definition.variables)
+        # Merge variables: preserve existing lifecycle variables, then apply workflow declarations
+        # Priority: existing state < workflow defaults < passed-in variables
+        # This preserves lifecycle variables (like unlocked_tools) that the step workflow doesn't declare
+        merged_variables = dict(existing.variables) if existing else {}
+        merged_variables.update(definition.variables)  # Override with workflow-declared defaults
         if variables:
-            merged_variables.update(variables)
+            merged_variables.update(variables)  # Override with passed-in values
 
         # Create state
         state = WorkflowState(

gobby/workflows/evaluator.py

@@ -23,7 +23,7 @@ def is_task_complete(task: Any) -> bool:
 
     A task is complete if:
     - status is 'closed', OR
-    - status is 'review' AND requires_user_review is False
+    - status is 'needs_review' AND requires_user_review is False
       (agent marked for visibility but doesn't need user sign-off)
 
     Tasks in 'review' with requires_user_review=True are NOT complete
@@ -38,7 +38,7 @@ def is_task_complete(task: Any) -> bool:
     if task.status == "closed":
         return True
     requires_user_review = getattr(task, "requires_user_review", False)
-    if task.status == "review" and not requires_user_review:
+    if task.status == "needs_review" and not requires_user_review:
         return True
     return False
 
@@ -55,7 +55,7 @@ def task_needs_user_review(task_manager: Any, task_id: str | None) -> bool:
         task_id: Task ID to check
 
     Returns:
-        True if task is in 'review' status AND has requires_user_review=True.
+        True if task is in 'needs_review' status AND has requires_user_review=True.
         Returns False if task_id is None or task not found.
     """
     if not task_id or not task_manager:
@@ -65,7 +65,7 @@ def task_needs_user_review(task_manager: Any, task_id: str | None) -> bool:
     if not task:
         return False
 
-    return bool(task.status == "review" and getattr(task, "requires_user_review", False))
+    return bool(task.status == "needs_review" and getattr(task, "requires_user_review", False))
 
 
 def task_tree_complete(task_manager: Any, task_id: str | list[str] | None) -> bool:
@@ -74,7 +74,7 @@ def task_tree_complete(task_manager: Any, task_id: str | list[str] | None) -> bo
 
     A task is complete if:
     - status is 'closed', OR
-    - status is 'review' AND requires_user_review is False
+    - status is 'needs_review' AND requires_user_review is False
 
     Used in workflow transition conditions like:
         when: "task_tree_complete(variables.session_task)"
@@ -283,6 +283,9 @@ class ConditionEvaluator:
                 "None": None,
                 "True": True,
                 "False": False,
+                # YAML/JSON use lowercase booleans
+                "true": True,
+                "false": False,
             }
 
             # Add plugin conditions as callable functions

gobby/workflows/lifecycle_evaluator.py

@@ -10,10 +10,10 @@ from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any, Literal
 
 from gobby.hooks.events import HookEvent, HookEventType, HookResponse
+from gobby.workflows.definitions import WorkflowDefinition, WorkflowState
 
 if TYPE_CHECKING:
     from .actions import ActionExecutor
-    from .definitions import WorkflowDefinition, WorkflowState
     from .evaluator import ConditionEvaluator
     from .loader import WorkflowLoader
     from .state_manager import WorkflowStateManager
@@ -123,28 +123,30 @@ async def evaluate_workflow_triggers(
     session_id = event.metadata.get("_platform_session_id") or "global"
 
     # Try to load existing state, or create new one
-    state = state_manager.get_state(session_id)
-    if state is None:
-        state = WorkflowState(
-            session_id=session_id,
-            workflow_name=workflow.name,
-            step="global",
-            step_entered_at=datetime.now(UTC),
-            step_action_count=0,
-            total_action_count=0,
-            artifacts=event.data.get("artifacts", {}) if event.data else {},
-            observations=[],
-            reflection_pending=False,
-            context_injected=False,
-            variables={},
-            task_list=None,
-            current_task_index=0,
-            files_modified_this_task=0,
-        )
-
-    # Merge context_data into state variables (context_data has session vars from earlier load)
+    # Track whether we created a new state to determine save behavior later
+    existing_state = state_manager.get_state(session_id)
+    state_was_created = existing_state is None
+    state: WorkflowState = existing_state or WorkflowState(
+        session_id=session_id,
+        workflow_name=workflow.name,
+        step="global",
+        step_entered_at=datetime.now(UTC),
+        step_action_count=0,
+        total_action_count=0,
+        artifacts=event.data.get("artifacts", {}) if event.data else {},
+        observations=[],
+        reflection_pending=False,
+        context_injected=False,
+        variables={},
+        task_list=None,
+        current_task_index=0,
+        files_modified_this_task=0,
+    )
+
+    # Merge context_data (workflow defaults) into state variables
+    # Persisted state values take precedence over workflow defaults
     if context_data:
-        state.variables.update(context_data)
+        state.variables = {**context_data, **state.variables}
 
     action_ctx = ActionContext(
         session_id=session_id,
@@ -236,11 +238,28 @@ async def evaluate_workflow_triggers(
                 exc_info=True,
             )
 
-    # Persist state changes (e.g., _injected_memory_ids from memory_recall_relevant)
+    # Persist state changes (e.g., _injected_memory_ids from memory_recall_relevant,
+    # unlocked_tools from track_schema_lookup)
     # Only save if we have a real session ID (not "global" fallback)
     # The workflow_states table has a FK to sessions, so we can't save for non-existent sessions
     if session_id != "global":
-        state_manager.save_state(state)
+        if state_was_created:
+            # We created a new lifecycle state - check for existing step workflow
+            # to avoid overwriting it with our new lifecycle state.
+            # Step workflows (activated via activate_workflow) have their own workflow_name.
+            current_state = state_manager.get_state(session_id)
+            is_step_workflow = (
+                current_state is not None
+                and current_state.workflow_name != "__lifecycle__"
+                and current_state.workflow_name != workflow.name
+            )
+            if not is_step_workflow:
+                state_manager.save_state(state)
+        else:
+            # We fetched an existing state (possibly a step workflow) and updated
+            # its variables. Safe to save since we're just persisting variable
+            # changes (like unlocked_tools), not changing workflow_name or step.
+            state_manager.save_state(state)
 
     final_context = "\n\n".join(injected_context) if injected_context else None
     logger.debug(
@@ -290,6 +309,11 @@ async def evaluate_lifecycle_triggers(
         logger.warning(f"Workflow '{workflow_name}' not found in project_path={project_path}")
         return HookResponse(decision="allow")
 
+    # Lifecycle triggers only apply to WorkflowDefinition, not PipelineDefinition
+    if not isinstance(workflow, WorkflowDefinition):
+        logger.debug(f"Workflow '{workflow_name}' is not a WorkflowDefinition, skipping triggers")
+        return HookResponse(decision="allow")
+
     logger.debug(
         f"Workflow '{workflow_name}' loaded, triggers={list(workflow.triggers.keys()) if workflow.triggers else []}"
     )
@@ -533,6 +557,10 @@ async def evaluate_all_lifecycle_workflows(
         for discovered in workflows:
             workflow = discovered.definition
 
+            # Skip PipelineDefinition - lifecycle triggers only for WorkflowDefinition
+            if not isinstance(workflow, WorkflowDefinition):
+                continue
+
             # Skip if this workflow+trigger has already been processed
             key = (workflow.name, trigger_name)
             if key in processed_triggers:
@@ -540,10 +568,11 @@ async def evaluate_all_lifecycle_workflows(
 
             # Merge workflow definition's default variables (lower priority than session state)
             # Precedence: session state > workflow YAML defaults
-            workflow_context = {**workflow.variables, **context_data}
+            # Update context_data directly so workflow variables propagate to response metadata
+            context_data = {**workflow.variables, **context_data}
 
             response = await evaluate_workflow_triggers(
-                workflow, event, workflow_context, state_manager, action_executor, evaluator
+                workflow, event, context_data, state_manager, action_executor, evaluator
             )
 
             # Accumulate context
@@ -594,6 +623,7 @@ async def evaluate_all_lifecycle_workflows(
                 )
             detect_task_claim_fn(event, state)
             detect_plan_mode_fn(event, state)
+            # Safe to save - we're updating variables on existing state, not changing workflow_name
             state_manager.save_state(state)
 
     # Detect plan mode from system reminders for BEFORE_AGENT events
@@ -609,6 +639,7 @@ async def evaluate_all_lifecycle_workflows(
                     step="",
                 )
             detect_plan_mode_from_context_fn(event, state)
+            # Safe to save - we're updating variables on existing state, not changing workflow_name
             state_manager.save_state(state)
 
     # Check for premature stop in active step workflows on STOP events
@@ -636,6 +667,7 @@ async def evaluate_all_lifecycle_workflows(
                     "path": str(w.path),
                 }
                 for w in workflows
-            ]
+            ],
+            "workflow_variables": context_data,
         },
     )