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

gobby/mcp_proxy/tools/spawn_agent.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import logging
 import uuid
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, cast
+from typing import TYPE_CHECKING, Any, Literal
 
 from gobby.agents.definitions import AgentDefinition, AgentDefinitionLoader
 from gobby.agents.isolation import (
@@ -28,6 +28,7 @@ from gobby.mcp_proxy.tools.internal import InternalToolRegistry
 from gobby.mcp_proxy.tools.tasks import resolve_task_id_for_mcp
 from gobby.utils.machine_id import get_machine_id
 from gobby.utils.project_context import get_project_context
+from gobby.workflows.loader import WorkflowLoader
 
 if TYPE_CHECKING:
     from gobby.agents.runner import AgentRunner
@@ -36,6 +37,82 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+async def _handle_self_mode(
+    workflow: str | None,
+    parent_session_id: str,
+    step_variables: dict[str, Any] | None,
+    initial_step: str | None,
+    workflow_loader: WorkflowLoader | None,
+    state_manager: Any | None,
+    session_manager: Any | None,
+    db: Any | None,
+    project_path: str | None,
+) -> dict[str, Any]:
+    """
+    Activate workflow on calling session instead of spawning a new agent.
+
+    This is the implementation for mode=self, which activates a workflow
+    on the parent session rather than creating a new child session.
+
+    Args:
+        workflow: Workflow name to activate
+        parent_session_id: Session to activate workflow on (the caller)
+        step_variables: Initial variables for the workflow
+        initial_step: Optional starting step (defaults to first step)
+        workflow_loader: WorkflowLoader instance
+        state_manager: WorkflowStateManager instance (or created from db if None)
+        session_manager: LocalSessionManager instance
+        db: Database instance
+        project_path: Project path for workflow lookup
+
+    Returns:
+        Dict with success status and activation details
+    """
+    if not workflow:
+        return {"success": False, "error": "mode: self requires a workflow to activate"}
+
+    # Create state_manager from db if not provided
+    effective_state_manager = state_manager
+    if effective_state_manager is None and db is not None:
+        from gobby.workflows.state_manager import WorkflowStateManager
+
+        effective_state_manager = WorkflowStateManager(db)
+
+    if not workflow_loader or not effective_state_manager or not session_manager or not db:
+        return {
+            "success": False,
+            "error": "mode: self requires workflow_loader, state_manager (or db), session_manager, and db",
+        }
+
+    # Import and call the existing activate_workflow function
+    from gobby.mcp_proxy.tools.workflows._lifecycle import activate_workflow
+
+    result = activate_workflow(
+        loader=workflow_loader,
+        state_manager=effective_state_manager,
+        session_manager=session_manager,
+        db=db,
+        name=workflow,
+        session_id=parent_session_id,
+        initial_step=initial_step,
+        variables=step_variables,
+        project_path=project_path,
+    )
+
+    if not result.get("success"):
+        return result
+
+    return {
+        "success": True,
+        "mode": "self",
+        "workflow_activated": workflow,
+        "session_id": parent_session_id,
+        "step": result.get("step"),
+        "steps": result.get("steps"),
+        "message": f"Workflow '{workflow}' activated on session {parent_session_id}",
+    }
+
+
 async def spawn_agent_impl(
     prompt: str,
     runner: AgentRunner,
@@ -53,7 +130,8 @@ async def spawn_agent_impl(
     clone_manager: Any | None = None,
     # Execution
     workflow: str | None = None,
-    mode: Literal["terminal", "embedded", "headless"] | None = None,
+    mode: Literal["terminal", "embedded", "headless", "self"] | None = None,
+    initial_step: str | None = None,  # For mode=self, start at specific step
     terminal: str = "auto",
     provider: str | None = None,
     model: str | None = None,
@@ -68,6 +146,11 @@ async def spawn_agent_impl(
     # Context
     parent_session_id: str | None = None,
     project_path: str | None = None,
+    # For mode=self (workflow activation on caller session)
+    workflow_loader: WorkflowLoader | None = None,
+    state_manager: Any | None = None,  # WorkflowStateManager
+    session_manager: Any | None = None,  # LocalSessionManager
+    db: Any | None = None,  # DatabaseProtocol
 ) -> dict[str, Any]:
     """
     Core spawn_agent implementation that can be called directly.
@@ -91,7 +174,7 @@ async def spawn_agent_impl(
         workflow: Workflow to use
         mode: Execution mode (terminal/embedded/headless)
         terminal: Terminal type for terminal mode
-        provider: AI provider (claude/gemini/codex)
+        provider: AI provider (claude/gemini/codex/cursor/windsurf/copilot)
         model: Model to use
         timeout: Timeout in seconds
         max_turns: Maximum conversation turns
@@ -116,18 +199,77 @@ async def spawn_agent_impl(
         effective_provider = agent_def.provider
     effective_provider = effective_provider or "claude"
 
-    effective_mode: Literal["terminal", "embedded", "headless"] | None = mode
+    effective_mode: Literal["terminal", "embedded", "headless", "self"] | None = mode
     if effective_mode is None and agent_def:
-        effective_mode = cast(Literal["terminal", "embedded", "headless"], agent_def.mode)
+        effective_mode = agent_def.get_effective_mode(workflow)
     effective_mode = effective_mode or "terminal"
 
-    effective_workflow = workflow
-    if effective_workflow is None and agent_def:
-        effective_workflow = agent_def.workflow
+    # Resolve workflow using agent_def's named workflows map
+    # Resolution order: explicit param > agent's workflows map > legacy workflow field
+    effective_workflow: str | None = None
+    if agent_def:
+        effective_workflow = agent_def.get_effective_workflow(workflow)
+    elif workflow:
+        effective_workflow = workflow
+
+    # Handle mode=self: activate workflow on caller session instead of spawning
+    if effective_mode == "self":
+        # Validate constraints
+        if effective_isolation != "current":
+            return {
+                "success": False,
+                "error": "mode: self is incompatible with isolation (worktree/clone). "
+                "Self mode activates a workflow on the calling session.",
+            }
+        if not effective_workflow:
+            return {
+                "success": False,
+                "error": "mode: self requires a workflow to activate",
+            }
+        if not parent_session_id:
+            return {
+                "success": False,
+                "error": "mode: self requires parent_session_id (the session to activate on)",
+            }
+
+        # Resolve step_variables for workflow activation
+        self_step_variables: dict[str, Any] | None = None
+        if task_id and task_manager:
+            # Resolve project context first for task resolution
+            ctx = get_project_context(Path(project_path) if project_path else None)
+            self_project_id = ctx.get("id") if ctx else None
+            if self_project_id:
+                try:
+                    self_task_id = resolve_task_id_for_mcp(task_manager, task_id, self_project_id)
+                    task = task_manager.get_task(self_task_id)
+                    if task:
+                        self_step_variables = {
+                            "assigned_task_id": f"#{task.seq_num}" if task.seq_num else self_task_id
+                        }
+                except Exception as e:
+                    logger.warning(f"Failed to resolve task_id {task_id}: {e}")
+
+        return await _handle_self_mode(
+            workflow=effective_workflow,
+            parent_session_id=parent_session_id,
+            step_variables=self_step_variables,
+            initial_step=initial_step,
+            workflow_loader=workflow_loader,
+            state_manager=state_manager,
+            session_manager=session_manager,
+            db=db,
+            project_path=project_path,
+        )
 
     effective_base_branch = base_branch
     if effective_base_branch is None and agent_def:
         effective_base_branch = agent_def.base_branch
+    # Auto-detect current branch if no base_branch specified
+    if effective_base_branch is None and git_manager:
+        try:
+            effective_base_branch = git_manager.get_current_branch()
+        except Exception:  # nosec B110 - fallback to default branch is intentional
+            effective_base_branch = None
     effective_base_branch = effective_base_branch or "main"
 
     effective_branch_prefix = None
@@ -250,7 +392,14 @@ async def spawn_agent_impl(
     session_id = str(uuid.uuid4())
     run_id = str(uuid.uuid4())
 
-    # 10. Execute spawn via SpawnExecutor
+    # 10. Build step_variables for workflow activation (e.g., assigned_task_id)
+    step_variables: dict[str, Any] | None = None
+    if resolved_task_id:
+        step_variables = {
+            "assigned_task_id": f"#{task_seq_num}" if task_seq_num else resolved_task_id
+        }
+
+    # 11. Execute spawn via SpawnExecutor
     spawn_request = SpawnRequest(
         prompt=enhanced_prompt,
         cwd=isolation_ctx.cwd,
@@ -262,8 +411,10 @@ async def spawn_agent_impl(
         parent_session_id=parent_session_id,
         project_id=project_id,
         workflow=effective_workflow,
+        step_variables=step_variables,
         worktree_id=isolation_ctx.worktree_id,
         clone_id=isolation_ctx.clone_id,
+        branch_name=isolation_ctx.branch_name,
         session_manager=runner._child_session_manager,
         machine_id=get_machine_id() or "unknown",
         sandbox_config=effective_sandbox_config,
@@ -314,6 +465,10 @@ def create_spawn_agent_registry(
     clone_storage: Any | None = None,
     clone_manager: Any | None = None,
     session_manager: Any | None = None,
+    workflow_loader: WorkflowLoader | None = None,
+    # For mode=self (workflow activation on caller session)
+    state_manager: Any | None = None,  # WorkflowStateManager
+    db: Any | None = None,  # DatabaseProtocol
 ) -> InternalToolRegistry:
     """
     Create a spawn_agent tool registry with the unified spawn_agent tool.
@@ -327,6 +482,9 @@ def create_spawn_agent_registry(
         clone_storage: Storage for clone records.
         clone_manager: Git manager for clone operations.
         session_manager: Session manager for resolving session references.
+        workflow_loader: Loader for workflow validation.
+        state_manager: WorkflowStateManager for mode=self activation.
+        db: Database instance for mode=self activation.
 
     Returns:
         InternalToolRegistry with spawn_agent tool registered.
@@ -345,8 +503,9 @@ def create_spawn_agent_registry(
         description="Unified agent spawning with isolation support",
     )
 
-    # Use provided loader or create default
+    # Use provided loaders or create defaults
     loader = agent_loader or AgentDefinitionLoader()
+    wf_loader = workflow_loader or WorkflowLoader()
 
     @registry.tool(
         name="spawn_agent",
@@ -367,7 +526,8 @@ def create_spawn_agent_registry(
         base_branch: str | None = None,
         # Execution
         workflow: str | None = None,
-        mode: Literal["terminal", "embedded", "headless"] | None = None,
+        mode: Literal["terminal", "embedded", "headless", "self"] | None = None,
+        initial_step: str | None = None,
         terminal: str = "auto",
         provider: str | None = None,
         model: str | None = None,
@@ -394,9 +554,11 @@ def create_spawn_agent_registry(
             branch_name: Git branch name (auto-generated from task if not provided)
             base_branch: Base branch for worktree/clone
             workflow: Workflow to use
-            mode: Execution mode (terminal/embedded/headless)
+            mode: Execution mode (terminal/embedded/headless/self).
+                  'self' activates workflow on caller session instead of spawning.
+            initial_step: For mode=self, start at specific step (defaults to first)
             terminal: Terminal type for terminal mode
-            provider: AI provider (claude/gemini/codex)
+            provider: AI provider (claude/gemini/codex/cursor/windsurf/copilot)
             model: Model to use
             timeout: Timeout in seconds
             max_turns: Maximum conversation turns
@@ -423,6 +585,53 @@ def create_spawn_agent_registry(
         if agent_def is None and agent != "generic":
             return {"success": False, "error": f"Agent '{agent}' not found"}
 
+        # Determine effective workflow using agent's named workflows map
+        # Resolution: explicit param > agent's workflows map > legacy workflow field
+        effective_workflow: str | None = None
+        inline_workflow_spec = None
+
+        if agent_def:
+            effective_workflow = agent_def.get_effective_workflow(workflow)
+
+            # Check if this is an inline workflow that needs registration
+            if workflow and agent_def.workflows and workflow in agent_def.workflows:
+                spec = agent_def.workflows[workflow]
+                if spec.is_inline():
+                    inline_workflow_spec = spec
+            elif (
+                not workflow
+                and agent_def.default_workflow
+                and agent_def.workflows
+                and agent_def.default_workflow in agent_def.workflows
+            ):
+                spec = agent_def.workflows[agent_def.default_workflow]
+                if spec.is_inline():
+                    inline_workflow_spec = spec
+        elif workflow:
+            effective_workflow = workflow
+
+        # Get project_path for workflow lookup
+        ctx = get_project_context(Path(project_path) if project_path else None)
+        wf_project_path = ctx.get("project_path") if ctx else None
+
+        # Register inline workflow if needed
+        if inline_workflow_spec and effective_workflow:
+            wf_loader.register_inline_workflow(
+                effective_workflow, inline_workflow_spec.model_dump(), project_path=wf_project_path
+            )
+
+        # Validate workflow exists if specified (skip for inline that we just registered)
+        if effective_workflow and not inline_workflow_spec:
+            loaded_workflow = wf_loader.load_workflow(
+                effective_workflow, project_path=wf_project_path
+            )
+            if loaded_workflow is None:
+                return {
+                    "success": False,
+                    "error": f"Workflow '{effective_workflow}' not found. "
+                    f"Check available workflows with list_workflows().",
+                }
+
         # Delegate to spawn_agent_impl
         return await spawn_agent_impl(
             prompt=prompt,
@@ -437,8 +646,9 @@ def create_spawn_agent_registry(
             git_manager=git_manager,
             clone_storage=clone_storage,
             clone_manager=clone_manager,
-            workflow=workflow,
+            workflow=effective_workflow,
             mode=mode,
+            initial_step=initial_step,
             terminal=terminal,
             provider=provider,
             model=model,
@@ -450,6 +660,11 @@ def create_spawn_agent_registry(
             sandbox_extra_paths=sandbox_extra_paths,
             parent_session_id=resolved_parent_session_id,
             project_path=project_path,
+            # For mode=self
+            workflow_loader=wf_loader,
+            state_manager=state_manager,
+            session_manager=session_manager,
+            db=db,
         )
 
     return registry

gobby/mcp_proxy/tools/tasks/_context.py

@@ -88,6 +88,14 @@ class RegistryContext:
             return project_id
         return None
 
+    def get_current_project_name(self) -> str | None:
+        """Get the current project name from context, or None if not in a project."""
+        ctx = get_project_context()
+        if ctx and ctx.get("name"):
+            name: str = ctx["name"]
+            return name
+        return None
+
     def get_workflow_state(self, session_id: str | None) -> WorkflowState | None:
         """Get workflow state for a session, if available."""
         if not session_id:

gobby/mcp_proxy/tools/tasks/_crud.py

@@ -335,6 +335,32 @@ def create_crud_registry(ctx: RegistryContext) -> InternalToolRegistry:
         except ValueError as e:
             return {"error": str(e)}
 
+        # Block closing tasks via update_task - must use close_task for proper workflow
+        if status is not None and status.lower() == "closed":
+            return {
+                "error": "Cannot set status to 'closed' via update_task. "
+                "Use close_task(task_id, commit_sha='...') to properly close tasks with commit linking."
+            }
+
+        # Block claiming tasks via update_task - must use claim_task for proper workflow
+        if status is not None and status.lower() == "in_progress":
+            return {
+                "error": "Cannot set status to 'in_progress' via update_task. "
+                "Use claim_task(task_id, session_id='...') to properly claim tasks with session tracking."
+            }
+        if assignee is not None:
+            return {
+                "error": "Cannot set assignee via update_task. "
+                "Use claim_task(task_id, session_id='...') to properly claim tasks with session tracking."
+            }
+
+        # Block needs_review status via update_task - must use mark_task_for_review for proper workflow
+        if status is not None and status.lower() in ("review", "needs_review"):
+            return {
+                "error": "Cannot set status to 'needs_review' via update_task. "
+                "Use mark_task_for_review(task_id, session_id='...') to properly route tasks for review."
+            }
+
         # Build kwargs only for non-None values to avoid overwriting with NULL
         kwargs: dict[str, Any] = {}
         if title is not None:
@@ -395,7 +421,7 @@ def create_crud_registry(ctx: RegistryContext) -> InternalToolRegistry:
                 },
                 "status": {
                     "type": "string",
-                    "description": "New status (open, in_progress, review, closed)",
+                    "description": "New status (open, in_progress, needs_review, closed)",
                     "default": None,
                 },
                 "priority": {"type": "integer", "description": "New priority", "default": None},

gobby/mcp_proxy/tools/tasks/_helpers.py

@@ -6,7 +6,7 @@ for task operations.
 
 # Reasons for which commit linking and validation are skipped when closing tasks
 SKIP_REASONS: frozenset[str] = frozenset(
-    {"duplicate", "already_implemented", "wont_fix", "obsolete"}
+    {"duplicate", "already_implemented", "wont_fix", "obsolete", "out_of_repo"}
 )
 
 # Category inference patterns mapping category to keywords/phrases

gobby/mcp_proxy/tools/tasks/_lifecycle.py

@@ -3,6 +3,7 @@
 Provides task lifecycle tools: close, reopen, delete, and label management.
 """
 
+import uuid
 from typing import Any
 
 from gobby.mcp_proxy.tools.internal import InternalToolRegistry
@@ -20,6 +21,15 @@ from gobby.storage.tasks import TaskNotFoundError
 from gobby.storage.worktrees import LocalWorktreeManager
 
 
+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
+
+
 def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
     """Create a registry with task lifecycle tools.
 
@@ -121,7 +131,7 @@ def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
                             "You must commit your changes and link them to the task before closing."
                         ),
                         "suggestion": (
-                            "Commit your changes with `[#task_id]` in the message, "
+                            f"Commit your changes with `[{ctx.get_current_project_name() or 'project'}-#task_id]` in the message, "
                             "or pass `commit_sha` to `close_task`."
                         ),
                     }
@@ -184,18 +194,20 @@ def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
         current_commit_sha = run_git_command(["git", "rev-parse", "--short", "HEAD"], cwd=cwd)
 
         if route_to_review:
-            # Route to review status instead of closing
-            # Task stays in review until user explicitly closes
+            # Route to needs_review status instead of closing
+            # Task stays in needs_review until user explicitly closes
             ctx.task_manager.update_task(
                 resolved_id,
-                status="review",
+                status="needs_review",
                 validation_override_reason=override_justification if store_override else None,
             )
 
             # Auto-link session if provided
             if resolved_session_id:
                 try:
-                    ctx.session_task_manager.link_task(resolved_session_id, resolved_id, "review")
+                    ctx.session_task_manager.link_task(
+                        resolved_session_id, resolved_id, "needs_review"
+                    )
                 except Exception:
                     pass  # nosec B110 - best-effort linking
 
@@ -235,7 +247,17 @@ def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
         if resolved_session_id:
             try:
                 state = ctx.workflow_state_manager.get_state(resolved_session_id)
-                if state and state.variables.get("claimed_task_id") == resolved_id:
+                if state:
+                    # Resolve claimed_task_id to UUID if it's a ref (backward compat)
+                    claimed_task_id = state.variables.get("claimed_task_id")
+                    if claimed_task_id and not _is_uuid(claimed_task_id):
+                        try:
+                            claimed_task = ctx.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
+                if state and claimed_task_id == resolved_id:
                     # Check if clear_task_on_close is enabled (default: True)
                     clear_on_close = state.variables.get("clear_task_on_close", True)
                     if clear_on_close:
@@ -267,7 +289,7 @@ def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
 
     registry.register(
         name="close_task",
-        description="Close a task. Pass commit_sha to link and close in one call: close_task(task_id, commit_sha='abc123'). Or include [#N] in commit message for auto-linking. Parent tasks require all children closed. Validation auto-skipped for: duplicate, already_implemented, wont_fix, obsolete.",
+        description="Close a task. Pass commit_sha to link and close in one call: close_task(task_id, commit_sha='abc123'). Or include [project-#N] in commit message for auto-linking. Parent tasks require all children closed. Validation auto-skipped for: duplicate, already_implemented, wont_fix, obsolete, out_of_repo.",
         input_schema={
             "type": "object",
             "properties": {
@@ -277,7 +299,7 @@ def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
                 },
                 "reason": {
                     "type": "string",
-                    "description": 'Reason for closing. Use "duplicate", "already_implemented", "wont_fix", or "obsolete" to auto-skip validation and commit check.',
+                    "description": 'Reason for closing. Use "duplicate", "already_implemented", "wont_fix", "obsolete", or "out_of_repo" to auto-skip validation and commit check.',
                     "default": "completed",
                 },
                 "changes_summary": {
@@ -567,6 +589,17 @@ def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
         except Exception:
             pass  # nosec B110 - best-effort linking
 
+        # Set task_claimed workflow variable (enables Edit/Write hooks)
+        # This mirrors create_task behavior in _crud.py
+        try:
+            state = ctx.workflow_state_manager.get_state(resolved_session_id)
+            if state:
+                state.variables["task_claimed"] = True
+                state.variables["claimed_task_id"] = resolved_id  # Always use UUID
+                ctx.workflow_state_manager.save_state(state)
+        except Exception:
+            pass  # nosec B110 - best-effort variable setting
+
         return {}
 
     registry.register(
@@ -594,4 +627,88 @@ def create_lifecycle_registry(ctx: RegistryContext) -> InternalToolRegistry:
         func=claim_task,
     )
 
+    def mark_task_for_review(
+        task_id: str,
+        session_id: str,
+        review_notes: str | None = None,
+    ) -> dict[str, Any]:
+        """Mark a task as ready for review.
+
+        Sets status to 'needs_review'. Use this when work is complete
+        but needs human verification before closing.
+
+        Args:
+            task_id: Task reference (#N, path, or UUID)
+            session_id: Session ID marking the task for review
+            review_notes: Optional notes for the reviewer
+
+        Returns:
+            Empty dict on success, or error dict with details.
+        """
+        # Resolve task reference (supports #N, path, UUID formats)
+        try:
+            resolved_id = resolve_task_id_for_mcp(ctx.task_manager, task_id)
+        except TaskNotFoundError as e:
+            return {"success": False, "error": str(e)}
+        except ValueError as e:
+            return {"success": False, "error": str(e)}
+
+        task = ctx.task_manager.get_task(resolved_id)
+        if not task:
+            return {"success": False, "error": f"Task {task_id} not found"}
+
+        # Resolve session_id to UUID (accepts #N, N, UUID, or prefix)
+        resolved_session_id = session_id
+        try:
+            resolved_session_id = ctx.resolve_session_id(session_id)
+        except ValueError:
+            pass  # Fall back to raw value if resolution fails
+
+        # Build update kwargs
+        update_kwargs: dict[str, Any] = {"status": "needs_review"}
+
+        # Append review notes to description if provided
+        if review_notes:
+            current_desc = task.description or ""
+            review_section = f"\n\n[Review Notes]\n{review_notes}"
+            update_kwargs["description"] = current_desc + review_section
+
+        # Update task status to needs_review
+        updated = ctx.task_manager.update_task(resolved_id, **update_kwargs)
+        if not updated:
+            return {"success": False, "error": f"Failed to mark task {task_id} for review"}
+
+        # Link task to session (best-effort, don't fail if this fails)
+        try:
+            ctx.session_task_manager.link_task(resolved_session_id, resolved_id, "needs_review")
+        except Exception:
+            pass  # nosec B110 - best-effort linking
+
+        return {}
+
+    registry.register(
+        name="mark_task_for_review",
+        description="Mark a task as ready for review. Sets status to 'needs_review'. Use this when work is complete but needs human verification before closing.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "task_id": {
+                    "type": "string",
+                    "description": "Task reference: #N (e.g., #1, #47), path (e.g., 1.2.3), or UUID",
+                },
+                "session_id": {
+                    "type": "string",
+                    "description": "Your session ID (accepts #N, N, UUID, or prefix). The session marking the task for review.",
+                },
+                "review_notes": {
+                    "type": "string",
+                    "description": "Optional notes for the reviewer explaining what was done and what to verify.",
+                    "default": None,
+                },
+            },
+            "required": ["task_id", "session_id"],
+        },
+        func=mark_task_for_review,
+    )
+
     return registry

gobby/mcp_proxy/tools/tasks/_lifecycle_validation.py

@@ -61,7 +61,8 @@ def validate_commit_requirements(
                 '- Task was already done: reason="already_implemented"\n'
                 '- Task is no longer needed: reason="obsolete"\n'
                 '- Task duplicates another: reason="duplicate"\n'
-                '- Decided not to do it: reason="wont_fix"'
+                '- Decided not to do it: reason="wont_fix"\n'
+                '- Changes outside repo (e.g., ~/.gobby/config.yaml): reason="out_of_repo"'
             ),
         )
 

gobby/mcp_proxy/tools/tasks/_search.py

@@ -43,7 +43,7 @@ def create_search_registry(ctx: RegistryContext) -> InternalToolRegistry:
 
         Args:
             query: Search query text (required). Natural language query.
-            status: Filter by status (open, in_progress, review, closed).
+            status: Filter by status (open, in_progress, needs_review, closed).
                 Can be a single status or comma-separated list.
             task_type: Filter by task type (task, bug, feature, epic)
             priority: Filter by priority (1=High, 2=Medium, 3=Low)