foundry-mcp 0.8.22__py3-none-any.whl

foundry_mcp/core/responses.py

@@ -0,0 +1,1624 @@
+"""
+Standard response contracts for MCP tool operations.
+Provides consistent response structures across all foundry-mcp tools.
+
+Response Schema Contract
+========================
+
+All MCP tool responses follow a standard structure:
+
+    {
+        "success": bool,       # Required: operation success/failure
+        "data": {...},         # Required: primary payload (empty dict on error)
+        "error": str | null,   # Required: error message or null on success
+        "meta": {              # Required: response metadata
+            "version": "response-v2",
+            "request_id": "req_abc123"?,
+            "warnings": ["..."]?,
+            "pagination": { ... }?,
+            "rate_limit": { ... }?,
+            "telemetry": { ... }?
+        }
+    }
+
+Metadata Semantics
+------------------
+
+Attach operational context through `meta` so every tool shares an identical
+envelope. The standard keys are:
+
+* `version` *(required)* – identifies the contract version (`response-v2`).
+* `request_id` *(should)* – correlation identifier propagated through logs.
+* `warnings` *(should)* – array of non-fatal issues for successful operations.
+* `pagination` *(may)* – cursor information (`cursor`, `has_more`, `total_count`).
+* `rate_limit` *(may)* – limit, remaining, reset timestamp, retry hints.
+* `telemetry` *(may)* – timing/performance metrics, downstream call counts, etc.
+
+Multi-Payload Tools
+-------------------
+
+Tools returning multiple payloads should nest each value under a named key:
+
+    data = {
+        "spec": {...},          # First payload
+        "tasks": [...],         # Second payload
+    }
+
+This ensures consumers can access each payload by name rather than relying
+on position or implicit structure.
+
+Edge Cases & Partial Payloads
+-----------------------------
+
+Empty Results (success=True):
+    When a query succeeds but finds no results, return success=True with
+    empty/partial data to distinguish from errors:
+
+    {"success": True, "data": {"tasks": [], "count": 0}, "error": None}
+
+Not Found (success=False):
+    When the requested resource doesn't exist, return success=False:
+
+    {"success": False, "data": {}, "error": "Spec not found: my-spec"}
+
+Blocked/Conditional States (success=True):
+    Dependency checks and similar queries return success=True with state info:
+
+    {
+        "success": True,
+        "data": {
+            "task_id": "task-1-2",
+            "can_start": False,
+            "blocked_by": [{"id": "task-1-1", "status": "pending"}]
+        },
+        "error": None,
+        "meta": {
+            "version": "response-v2",
+            "warnings": ["Task currently blocked"]
+        }
+    }
+
+Key Principle:
+    - `success=True` means the operation executed correctly (even if the result is empty).
+    - `success=False` means the operation failed to execute; include actionable error details.
+    - Keep business data inside `data` and operational context inside `meta`.
+"""
+
+import json
+import logging
+import subprocess
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, Mapping, Optional, Sequence, Union
+
+from foundry_mcp.core.context import get_correlation_id
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorCode(str, Enum):
+    """Machine-readable error codes for MCP tool responses.
+
+    Use these canonical codes in `error_code` fields to enable consistent
+    client-side error handling. Codes follow SCREAMING_SNAKE_CASE convention.
+
+    Categories:
+        - Validation (input errors)
+        - Resource (not found, conflict)
+        - Access (auth, permissions, rate limits)
+        - System (internal, unavailable)
+    """
+
+    # Validation errors
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    INVALID_FORMAT = "INVALID_FORMAT"
+    MISSING_REQUIRED = "MISSING_REQUIRED"
+    INVALID_PARENT = "INVALID_PARENT"
+    INVALID_POSITION = "INVALID_POSITION"
+    INVALID_REGEX_PATTERN = "INVALID_REGEX_PATTERN"
+    PATTERN_TOO_BROAD = "PATTERN_TOO_BROAD"
+
+    # Resource errors
+    NOT_FOUND = "NOT_FOUND"
+    SPEC_NOT_FOUND = "SPEC_NOT_FOUND"
+    TASK_NOT_FOUND = "TASK_NOT_FOUND"
+    PHASE_NOT_FOUND = "PHASE_NOT_FOUND"
+    DEPENDENCY_NOT_FOUND = "DEPENDENCY_NOT_FOUND"
+    BACKUP_NOT_FOUND = "BACKUP_NOT_FOUND"
+    NO_MATCHES_FOUND = "NO_MATCHES_FOUND"
+    DUPLICATE_ENTRY = "DUPLICATE_ENTRY"
+    CONFLICT = "CONFLICT"
+    CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY"
+    SELF_REFERENCE = "SELF_REFERENCE"
+
+    # Access errors
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN = "FORBIDDEN"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+    FEATURE_DISABLED = "FEATURE_DISABLED"
+
+    # System errors
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+    UNAVAILABLE = "UNAVAILABLE"
+    RESOURCE_BUSY = "RESOURCE_BUSY"
+    BACKUP_CORRUPTED = "BACKUP_CORRUPTED"
+    ROLLBACK_FAILED = "ROLLBACK_FAILED"
+    COMPARISON_FAILED = "COMPARISON_FAILED"
+    OPERATION_FAILED = "OPERATION_FAILED"
+
+    # AI/LLM Provider errors
+    AI_NO_PROVIDER = "AI_NO_PROVIDER"
+    AI_PROVIDER_TIMEOUT = "AI_PROVIDER_TIMEOUT"
+    AI_PROVIDER_ERROR = "AI_PROVIDER_ERROR"
+    AI_CONTEXT_TOO_LARGE = "AI_CONTEXT_TOO_LARGE"
+    AI_PROMPT_NOT_FOUND = "AI_PROMPT_NOT_FOUND"
+    AI_CACHE_STALE = "AI_CACHE_STALE"
+
+
+class ErrorType(str, Enum):
+    """Error categories for routing and client-side handling.
+
+    Each type corresponds to an HTTP status code analog and indicates
+    whether the operation should be retried.
+
+    See docs/codebase_standards/mcp_response_schema.md for the full mapping.
+    """
+
+    VALIDATION = "validation"  # 400 - No retry, fix input
+    AUTHENTICATION = "authentication"  # 401 - No retry, re-authenticate
+    AUTHORIZATION = "authorization"  # 403 - No retry
+    NOT_FOUND = "not_found"  # 404 - No retry
+    CONFLICT = "conflict"  # 409 - Maybe retry, check state
+    RATE_LIMIT = "rate_limit"  # 429 - Yes, after delay
+    FEATURE_FLAG = "feature_flag"  # 403 - No retry, check flag status
+    INTERNAL = "internal"  # 500 - Yes, with backoff
+    UNAVAILABLE = "unavailable"  # 503 - Yes, with backoff
+    AI_PROVIDER = "ai_provider"  # AI-specific - Retry varies by error
+
+
+@dataclass
+class ToolResponse:
+    """
+    Standard response structure for MCP tool operations.
+
+    All tool handlers should return data that can be serialized to this format,
+    ensuring consistent API responses across the codebase.
+
+    Attributes:
+        success: Whether the operation completed successfully
+        data: The primary payload (operation-specific structured data)
+        error: Error message if success is False, None otherwise
+        meta: Response metadata including version identifier
+    """
+
+    success: bool
+    data: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+    meta: Dict[str, Any] = field(default_factory=lambda: {"version": "response-v2"})
+
+
+def _build_meta(
+    *,
+    request_id: Optional[str] = None,
+    warnings: Optional[Sequence[str]] = None,
+    pagination: Optional[Mapping[str, Any]] = None,
+    rate_limit: Optional[Mapping[str, Any]] = None,
+    telemetry: Optional[Mapping[str, Any]] = None,
+    extra: Optional[Mapping[str, Any]] = None,
+    auto_inject_request_id: bool = True,
+) -> Dict[str, Any]:
+    """Construct a metadata payload that always includes the response version.
+
+    Args:
+        request_id: Explicit correlation ID (takes precedence if provided)
+        warnings: Non-fatal issues to surface
+        pagination: Cursor metadata for list results
+        rate_limit: Rate limit state
+        telemetry: Timing/performance metadata
+        extra: Arbitrary extra metadata to merge
+        auto_inject_request_id: If True (default), auto-inject correlation_id
+            from context when request_id is not explicitly provided
+    """
+    meta: Dict[str, Any] = {"version": "response-v2"}
+
+    # Auto-inject request_id from context if not explicitly provided
+    effective_request_id = request_id
+    if effective_request_id is None and auto_inject_request_id:
+        effective_request_id = get_correlation_id() or None
+
+    if effective_request_id:
+        meta["request_id"] = effective_request_id
+    if warnings:
+        meta["warnings"] = list(warnings)
+    if pagination:
+        meta["pagination"] = dict(pagination)
+    if rate_limit:
+        meta["rate_limit"] = dict(rate_limit)
+    if telemetry:
+        meta["telemetry"] = dict(telemetry)
+    if extra:
+        meta.update(dict(extra))
+
+    return meta
+
+
+def success_response(
+    data: Optional[Mapping[str, Any]] = None,
+    *,
+    warnings: Optional[Sequence[str]] = None,
+    pagination: Optional[Mapping[str, Any]] = None,
+    rate_limit: Optional[Mapping[str, Any]] = None,
+    telemetry: Optional[Mapping[str, Any]] = None,
+    request_id: Optional[str] = None,
+    meta: Optional[Mapping[str, Any]] = None,
+    **fields: Any,
+) -> ToolResponse:
+    """Create a standardized success response.
+
+    Args:
+        data: Optional mapping used as the base payload.
+        warnings: Non-fatal issues to surface in ``meta.warnings``.
+        pagination: Cursor metadata for list results.
+        rate_limit: Rate limit state (limit, remaining, reset_at, etc.).
+        telemetry: Timing/performance metadata.
+        request_id: Correlation identifier propagated through logs/traces.
+        meta: Arbitrary extra metadata to merge into ``meta``.
+        **fields: Additional payload fields (shorthand for ``data.update``).
+    """
+    payload: Dict[str, Any] = {}
+    if data:
+        payload.update(dict(data))
+    if fields:
+        payload.update(fields)
+
+    meta_payload = _build_meta(
+        request_id=request_id,
+        warnings=warnings,
+        pagination=pagination,
+        rate_limit=rate_limit,
+        telemetry=telemetry,
+        extra=meta,
+    )
+
+    return ToolResponse(success=True, data=payload, error=None, meta=meta_payload)
+
+
+def error_response(
+    message: str,
+    *,
+    data: Optional[Mapping[str, Any]] = None,
+    error_code: Optional[Union[ErrorCode, str]] = None,
+    error_type: Optional[Union[ErrorType, str]] = None,
+    remediation: Optional[str] = None,
+    details: Optional[Mapping[str, Any]] = None,
+    request_id: Optional[str] = None,
+    rate_limit: Optional[Mapping[str, Any]] = None,
+    telemetry: Optional[Mapping[str, Any]] = None,
+    meta: Optional[Mapping[str, Any]] = None,
+) -> ToolResponse:
+    """Create a standardized error response.
+
+    Args:
+        message: Human-readable description of the failure.
+        data: Optional mapping with additional machine-readable context.
+        error_code: Canonical error code (use ``ErrorCode`` enum or string,
+            e.g., ``ErrorCode.VALIDATION_ERROR`` or ``"VALIDATION_ERROR"``).
+        error_type: Error category for routing (use ``ErrorType`` enum or string,
+            e.g., ``ErrorType.VALIDATION`` or ``"validation"``).
+        remediation: User-facing guidance on how to fix the issue.
+        details: Nested structure describing validation failures or metadata.
+        request_id: Correlation identifier propagated through logs/traces.
+        rate_limit: Rate limit state to help clients back off correctly.
+        telemetry: Timing/performance metadata captured before failure.
+        meta: Arbitrary extra metadata to merge into ``meta``.
+
+    Example:
+        >>> error_response(
+        ...     "Validation failed: spec_id is required",
+        ...     error_code=ErrorCode.MISSING_REQUIRED,
+        ...     error_type=ErrorType.VALIDATION,
+        ...     remediation="Provide a non-empty spec_id parameter",
+        ... )
+    """
+    payload: Dict[str, Any] = {}
+    if data:
+        payload.update(dict(data))
+
+    effective_error_code: Union[ErrorCode, str] = (
+        error_code if error_code is not None else ErrorCode.INTERNAL_ERROR
+    )
+    effective_error_type: Union[ErrorType, str] = (
+        error_type if error_type is not None else ErrorType.INTERNAL
+    )
+
+    if "error_code" not in payload:
+        payload["error_code"] = (
+            effective_error_code.value
+            if isinstance(effective_error_code, Enum)
+            else effective_error_code
+        )
+    if "error_type" not in payload:
+        payload["error_type"] = (
+            effective_error_type.value
+            if isinstance(effective_error_type, Enum)
+            else effective_error_type
+        )
+    if remediation is not None and "remediation" not in payload:
+        payload["remediation"] = remediation
+    if details and "details" not in payload:
+        payload["details"] = dict(details)
+
+    meta_payload = _build_meta(
+        request_id=request_id,
+        rate_limit=rate_limit,
+        telemetry=telemetry,
+        extra=meta,
+    )
+
+    return ToolResponse(success=False, data=payload, error=message, meta=meta_payload)
+
+
+# ---------------------------------------------------------------------------
+# Specialized Error Helpers
+# ---------------------------------------------------------------------------
+
+
+def validation_error(
+    message: str,
+    *,
+    field: Optional[str] = None,
+    details: Optional[Mapping[str, Any]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create a validation error response (HTTP 400 analog).
+
+    Args:
+        message: Human-readable description of the validation failure.
+        field: The field that failed validation.
+        details: Additional context (e.g., constraint violated, value received).
+        remediation: Guidance on how to fix the input.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> validation_error(
+        ...     "Invalid email format",
+        ...     field="email",
+        ...     remediation="Provide email in format: user@domain.com",
+        ... )
+    """
+    error_details = dict(details) if details else {}
+    if field and "field" not in error_details:
+        error_details["field"] = field
+
+    return error_response(
+        message,
+        error_code=ErrorCode.VALIDATION_ERROR,
+        error_type=ErrorType.VALIDATION,
+        details=error_details if error_details else None,
+        remediation=remediation,
+        request_id=request_id,
+    )
+
+
+def not_found_error(
+    resource_type: str,
+    resource_id: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create a not found error response (HTTP 404 analog).
+
+    Args:
+        resource_type: Type of resource (e.g., "Spec", "Task", "User").
+        resource_id: Identifier of the missing resource.
+        remediation: Guidance on how to resolve (defaults to verification hint).
+        request_id: Correlation identifier.
+
+    Example:
+        >>> not_found_error("Spec", "my-spec-001")
+    """
+    return error_response(
+        f"{resource_type} '{resource_id}' not found",
+        error_code=ErrorCode.NOT_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data={"resource_type": resource_type, "resource_id": resource_id},
+        remediation=remediation or f"Verify the {resource_type.lower()} ID exists.",
+        request_id=request_id,
+    )
+
+
+def rate_limit_error(
+    limit: int,
+    period: str,
+    retry_after_seconds: int,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create a rate limit error response (HTTP 429 analog).
+
+    Args:
+        limit: Maximum requests allowed in the period.
+        period: Time window (e.g., "minute", "hour").
+        retry_after_seconds: Seconds until client can retry.
+        remediation: Guidance on how to proceed.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> rate_limit_error(100, "minute", 45)
+    """
+    return error_response(
+        f"Rate limit exceeded: {limit} requests per {period}",
+        error_code=ErrorCode.RATE_LIMIT_EXCEEDED,
+        error_type=ErrorType.RATE_LIMIT,
+        data={"retry_after_seconds": retry_after_seconds},
+        rate_limit={
+            "limit": limit,
+            "period": period,
+            "retry_after": retry_after_seconds,
+        },
+        remediation=remediation
+        or f"Wait {retry_after_seconds} seconds before retrying.",
+        request_id=request_id,
+    )
+
+
+def unauthorized_error(
+    message: str = "Authentication required",
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an unauthorized error response (HTTP 401 analog).
+
+    Args:
+        message: Human-readable description.
+        remediation: Guidance on how to authenticate.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> unauthorized_error("Invalid API key")
+    """
+    return error_response(
+        message,
+        error_code=ErrorCode.UNAUTHORIZED,
+        error_type=ErrorType.AUTHENTICATION,
+        remediation=remediation or "Provide valid authentication credentials.",
+        request_id=request_id,
+    )
+
+
+def forbidden_error(
+    message: str,
+    *,
+    required_permission: Optional[str] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create a forbidden error response (HTTP 403 analog).
+
+    Args:
+        message: Human-readable description.
+        required_permission: The permission needed for this operation.
+        remediation: Guidance on how to obtain access.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> forbidden_error(
+        ...     "Cannot delete project",
+        ...     required_permission="project:delete",
+        ... )
+    """
+    data: Dict[str, Any] = {}
+    if required_permission:
+        data["required_permission"] = required_permission
+
+    return error_response(
+        message,
+        error_code=ErrorCode.FORBIDDEN,
+        error_type=ErrorType.AUTHORIZATION,
+        data=data if data else None,
+        remediation=remediation
+        or "Request appropriate permissions from the resource owner.",
+        request_id=request_id,
+    )
+
+
+def conflict_error(
+    message: str,
+    *,
+    details: Optional[Mapping[str, Any]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create a conflict error response (HTTP 409 analog).
+
+    Args:
+        message: Human-readable description of the conflict.
+        details: Context about the conflicting state.
+        remediation: Guidance on how to resolve the conflict.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> conflict_error(
+        ...     "Resource already exists",
+        ...     details={"existing_id": "spec-001"},
+        ... )
+    """
+    return error_response(
+        message,
+        error_code=ErrorCode.CONFLICT,
+        error_type=ErrorType.CONFLICT,
+        details=details,
+        remediation=remediation or "Check current state and retry if appropriate.",
+        request_id=request_id,
+    )
+
+
+def internal_error(
+    message: str = "An internal error occurred",
+    *,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an internal error response (HTTP 500 analog).
+
+    Args:
+        message: Human-readable description (keep vague for security).
+        request_id: Correlation identifier for log correlation.
+
+    Example:
+        >>> internal_error(request_id="req_abc123")
+    """
+    remediation = "Please try again. If the problem persists, contact support."
+    if request_id:
+        remediation += f" Reference: {request_id}"
+
+    return error_response(
+        message,
+        error_code=ErrorCode.INTERNAL_ERROR,
+        error_type=ErrorType.INTERNAL,
+        remediation=remediation,
+        request_id=request_id,
+    )
+
+
+def unavailable_error(
+    message: str = "Service temporarily unavailable",
+    *,
+    retry_after_seconds: Optional[int] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an unavailable error response (HTTP 503 analog).
+
+    Args:
+        message: Human-readable description.
+        retry_after_seconds: Suggested retry delay.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> unavailable_error("Database maintenance in progress", retry_after_seconds=300)
+    """
+    data: Dict[str, Any] = {}
+    if retry_after_seconds:
+        data["retry_after_seconds"] = retry_after_seconds
+
+    remediation = "Please retry with exponential backoff."
+    if retry_after_seconds:
+        remediation = f"Retry after {retry_after_seconds} seconds."
+
+    return error_response(
+        message,
+        error_code=ErrorCode.UNAVAILABLE,
+        error_type=ErrorType.UNAVAILABLE,
+        data=data if data else None,
+        remediation=remediation,
+        request_id=request_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Spec Modification Error Helpers
+# ---------------------------------------------------------------------------
+
+
+def circular_dependency_error(
+    task_id: str,
+    target_id: str,
+    *,
+    cycle_path: Optional[Sequence[str]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for circular dependency detection.
+
+    Use when a move or dependency operation would create a cycle.
+
+    Args:
+        task_id: The task being moved or modified.
+        target_id: The target parent or dependency that would create a cycle.
+        cycle_path: Optional sequence showing the dependency cycle path.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> circular_dependency_error("task-3", "task-1", cycle_path=["task-1", "task-2", "task-3"])
+    """
+    data: Dict[str, Any] = {
+        "task_id": task_id,
+        "target_id": target_id,
+    }
+    if cycle_path:
+        data["cycle_path"] = list(cycle_path)
+
+    return error_response(
+        f"Circular dependency detected: {task_id} cannot depend on {target_id}",
+        error_code=ErrorCode.CIRCULAR_DEPENDENCY,
+        error_type=ErrorType.CONFLICT,
+        data=data,
+        remediation=remediation
+        or "Remove an existing dependency to break the cycle before adding this one.",
+        request_id=request_id,
+    )
+
+
+def invalid_parent_error(
+    task_id: str,
+    target_parent: str,
+    reason: str,
+    *,
+    valid_parents: Optional[Sequence[str]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for invalid parent in move operation.
+
+    Use when a task cannot be moved to the specified parent.
+
+    Args:
+        task_id: The task being moved.
+        target_parent: The invalid target parent.
+        reason: Why the parent is invalid (e.g., "is a task, not a phase").
+        valid_parents: Optional list of valid parent IDs.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> invalid_parent_error("task-3-1", "task-2-1", "target is a task, not a phase")
+    """
+    data: Dict[str, Any] = {
+        "task_id": task_id,
+        "target_parent": target_parent,
+        "reason": reason,
+    }
+    if valid_parents:
+        data["valid_parents"] = list(valid_parents)
+
+    return error_response(
+        f"Invalid parent '{target_parent}' for task '{task_id}': {reason}",
+        error_code=ErrorCode.INVALID_PARENT,
+        error_type=ErrorType.VALIDATION,
+        data=data,
+        remediation=remediation or "Specify a valid phase or parent task as the target.",
+        request_id=request_id,
+    )
+
+
+def self_reference_error(
+    task_id: str,
+    operation: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for self-referencing operations.
+
+    Use when a task references itself in dependencies or move operations.
+
+    Args:
+        task_id: The task that references itself.
+        operation: The operation attempted (e.g., "add-dependency", "move").
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> self_reference_error("task-1-1", "add-dependency")
+    """
+    return error_response(
+        f"Task '{task_id}' cannot reference itself in {operation}",
+        error_code=ErrorCode.SELF_REFERENCE,
+        error_type=ErrorType.VALIDATION,
+        data={"task_id": task_id, "operation": operation},
+        remediation=remediation or "Specify a different task ID as the target.",
+        request_id=request_id,
+    )
+
+
+def dependency_not_found_error(
+    task_id: str,
+    dependency_id: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for missing dependency in remove operation.
+
+    Use when trying to remove a dependency that doesn't exist.
+
+    Args:
+        task_id: The task being modified.
+        dependency_id: The dependency that wasn't found.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> dependency_not_found_error("task-1-1", "task-2-1")
+    """
+    return error_response(
+        f"Dependency '{dependency_id}' not found on task '{task_id}'",
+        error_code=ErrorCode.DEPENDENCY_NOT_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data={"task_id": task_id, "dependency_id": dependency_id},
+        remediation=remediation
+        or "Check existing dependencies using task info before removing.",
+        request_id=request_id,
+    )
+
+
+def invalid_position_error(
+    item_id: str,
+    position: int,
+    max_position: int,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for invalid position in move/reorder operation.
+
+    Use when the specified position is out of valid range.
+
+    Args:
+        item_id: The item being moved (phase or task ID).
+        position: The invalid position specified.
+        max_position: The maximum valid position.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> invalid_position_error("phase-3", 10, 5)
+    """
+    return error_response(
+        f"Invalid position {position} for '{item_id}': must be 1-{max_position}",
+        error_code=ErrorCode.INVALID_POSITION,
+        error_type=ErrorType.VALIDATION,
+        data={
+            "item_id": item_id,
+            "position": position,
+            "max_position": max_position,
+            "valid_range": f"1-{max_position}",
+        },
+        remediation=remediation or f"Specify a position between 1 and {max_position}.",
+        request_id=request_id,
+    )
+
+
+def invalid_regex_error(
+    pattern: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for invalid regex pattern.
+
+    Use when a find/replace pattern is not valid regex.
+
+    Args:
+        pattern: The invalid regex pattern.
+        error_detail: The regex error message.
+        remediation: Guidance on how to fix the pattern.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> invalid_regex_error("[unclosed", "unterminated character set")
+    """
+    return error_response(
+        f"Invalid regex pattern: {error_detail}",
+        error_code=ErrorCode.INVALID_REGEX_PATTERN,
+        error_type=ErrorType.VALIDATION,
+        data={"pattern": pattern, "error_detail": error_detail},
+        remediation=remediation
+        or "Check regex syntax. Use raw strings and escape special characters.",
+        request_id=request_id,
+    )
+
+
+def pattern_too_broad_error(
+    pattern: str,
+    match_count: int,
+    max_matches: int,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for overly broad patterns.
+
+    Use when a find/replace pattern matches too many items.
+
+    Args:
+        pattern: The pattern that matched too broadly.
+        match_count: Number of matches found.
+        max_matches: Maximum allowed matches.
+        remediation: Guidance on how to narrow the pattern.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> pattern_too_broad_error(".*", 500, 100)
+    """
+    return error_response(
+        f"Pattern too broad: {match_count} matches exceeds limit of {max_matches}",
+        error_code=ErrorCode.PATTERN_TOO_BROAD,
+        error_type=ErrorType.VALIDATION,
+        data={
+            "pattern": pattern,
+            "match_count": match_count,
+            "max_matches": max_matches,
+        },
+        remediation=remediation
+        or "Use a more specific pattern or apply to a narrower scope.",
+        request_id=request_id,
+    )
+
+
+def no_matches_error(
+    pattern: str,
+    scope: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for patterns with no matches.
+
+    Use when a find/replace pattern matches nothing.
+
+    Args:
+        pattern: The pattern that found no matches.
+        scope: Where the search was performed (e.g., "spec", "phase-1").
+        remediation: Guidance on what to check.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> no_matches_error("deprecated_function", "spec my-spec-001")
+    """
+    return error_response(
+        f"No matches found for pattern '{pattern}' in {scope}",
+        error_code=ErrorCode.NO_MATCHES_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data={"pattern": pattern, "scope": scope},
+        remediation=remediation
+        or "Verify the pattern and scope. Use dry-run to preview matches.",
+        request_id=request_id,
+    )
+
+
+def backup_not_found_error(
+    spec_id: str,
+    backup_id: Optional[str] = None,
+    *,
+    available_backups: Optional[Sequence[str]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for missing backup.
+
+    Use when a rollback or diff references a non-existent backup.
+
+    Args:
+        spec_id: The spec whose backup is missing.
+        backup_id: The specific backup ID that wasn't found.
+        available_backups: Optional list of available backup IDs.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> backup_not_found_error("my-spec-001", "backup-2024-01-15")
+    """
+    data: Dict[str, Any] = {"spec_id": spec_id}
+    if backup_id:
+        data["backup_id"] = backup_id
+    if available_backups:
+        data["available_backups"] = list(available_backups)
+
+    message = f"Backup not found for spec '{spec_id}'"
+    if backup_id:
+        message = f"Backup '{backup_id}' not found for spec '{spec_id}'"
+
+    return error_response(
+        message,
+        error_code=ErrorCode.BACKUP_NOT_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data=data,
+        remediation=remediation or "List available backups using spec action='history'.",
+        request_id=request_id,
+    )
+
+
+def backup_corrupted_error(
+    spec_id: str,
+    backup_id: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for corrupted backup.
+
+    Use when a backup file exists but cannot be loaded.
+
+    Args:
+        spec_id: The spec whose backup is corrupted.
+        backup_id: The corrupted backup identifier.
+        error_detail: Description of the corruption.
+        remediation: Guidance on how to recover.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> backup_corrupted_error("my-spec", "backup-001", "Invalid JSON structure")
+    """
+    return error_response(
+        f"Backup '{backup_id}' for spec '{spec_id}' is corrupted: {error_detail}",
+        error_code=ErrorCode.BACKUP_CORRUPTED,
+        error_type=ErrorType.INTERNAL,
+        data={
+            "spec_id": spec_id,
+            "backup_id": backup_id,
+            "error_detail": error_detail,
+        },
+        remediation=remediation
+        or "Try an earlier backup or restore from version control.",
+        request_id=request_id,
+    )
+
+
+def rollback_failed_error(
+    spec_id: str,
+    backup_id: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for failed rollback operation.
+
+    Use when a rollback operation fails after starting.
+
+    Args:
+        spec_id: The spec being rolled back.
+        backup_id: The backup being restored from.
+        error_detail: What went wrong during rollback.
+        remediation: Guidance on how to recover.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> rollback_failed_error("my-spec", "backup-001", "Write permission denied")
+    """
+    return error_response(
+        f"Rollback failed for spec '{spec_id}' from backup '{backup_id}': {error_detail}",
+        error_code=ErrorCode.ROLLBACK_FAILED,
+        error_type=ErrorType.INTERNAL,
+        data={
+            "spec_id": spec_id,
+            "backup_id": backup_id,
+            "error_detail": error_detail,
+        },
+        remediation=remediation
+        or "Check file permissions. A safety backup was created before rollback attempt.",
+        request_id=request_id,
+    )
+
+
+def comparison_failed_error(
+    source: str,
+    target: str,
+    error_detail: str,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for failed diff/comparison operation.
+
+    Use when a spec comparison operation fails.
+
+    Args:
+        source: The source spec or backup being compared.
+        target: The target spec or backup being compared.
+        error_detail: What went wrong during comparison.
+        remediation: Guidance on how to resolve.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> comparison_failed_error("my-spec-v1", "my-spec-v2", "Schema version mismatch")
+    """
+    return error_response(
+        f"Comparison failed between '{source}' and '{target}': {error_detail}",
+        error_code=ErrorCode.COMPARISON_FAILED,
+        error_type=ErrorType.INTERNAL,
+        data={
+            "source": source,
+            "target": target,
+            "error_detail": error_detail,
+        },
+        remediation=remediation
+        or "Ensure both specs are valid and use compatible schema versions.",
+        request_id=request_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# AI/LLM Provider Error Helpers
+# ---------------------------------------------------------------------------
+
+
+def ai_no_provider_error(
+    message: str = "No AI provider available",
+    *,
+    required_providers: Optional[Sequence[str]] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for when no AI provider is available.
+
+    Use when an AI consultation is requested but no providers are configured
+    or all configured providers have failed availability checks.
+
+    Args:
+        message: Human-readable description.
+        required_providers: List of provider IDs that were checked.
+        remediation: Guidance on how to configure a provider.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> ai_no_provider_error(
+        ...     "No AI provider available for plan review",
+        ...     required_providers=["gemini", "cursor-agent", "codex"],
+        ... )
+    """
+    data: Dict[str, Any] = {}
+    if required_providers:
+        data["required_providers"] = list(required_providers)
+
+    default_remediation = (
+        "Configure an AI provider: set GEMINI_API_KEY, OPENAI_API_KEY, "
+        "or ANTHROPIC_API_KEY environment variable, or ensure cursor-agent is available."
+    )
+
+    return error_response(
+        message,
+        error_code=ErrorCode.AI_NO_PROVIDER,
+        error_type=ErrorType.AI_PROVIDER,
+        data=data if data else None,
+        remediation=remediation or default_remediation,
+        request_id=request_id,
+    )
+
+
+def ai_provider_timeout_error(
+    provider_id: str,
+    timeout_seconds: int,
+    *,
+    message: Optional[str] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for AI provider execution timeout.
+
+    Use when an AI provider call exceeds the configured timeout limit.
+
+    Args:
+        provider_id: The provider that timed out (e.g., "gemini", "codex").
+        timeout_seconds: The timeout that was exceeded.
+        message: Human-readable description (auto-generated if not provided).
+        remediation: Guidance on how to handle the timeout.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> ai_provider_timeout_error("gemini", 300)
+    """
+    default_message = f"AI provider '{provider_id}' timed out after {timeout_seconds}s"
+
+    return error_response(
+        message or default_message,
+        error_code=ErrorCode.AI_PROVIDER_TIMEOUT,
+        error_type=ErrorType.AI_PROVIDER,
+        data={
+            "provider_id": provider_id,
+            "timeout_seconds": timeout_seconds,
+        },
+        remediation=remediation
+        or (
+            "Try again with a smaller context, increase the timeout, "
+            "or use a different provider."
+        ),
+        request_id=request_id,
+    )
+
+
+def ai_provider_error(
+    provider_id: str,
+    error_detail: str,
+    *,
+    status_code: Optional[int] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for when an AI provider returns an error.
+
+    Use when an AI provider API call fails with an error response.
+
+    Args:
+        provider_id: The provider that returned the error.
+        error_detail: The error message from the provider.
+        status_code: HTTP status code from the provider (if applicable).
+        remediation: Guidance on how to resolve the issue.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> ai_provider_error("gemini", "Invalid API key", status_code=401)
+    """
+    data: Dict[str, Any] = {
+        "provider_id": provider_id,
+        "error_detail": error_detail,
+    }
+    if status_code is not None:
+        data["status_code"] = status_code
+
+    return error_response(
+        f"AI provider '{provider_id}' returned error: {error_detail}",
+        error_code=ErrorCode.AI_PROVIDER_ERROR,
+        error_type=ErrorType.AI_PROVIDER,
+        data=data,
+        remediation=remediation
+        or (
+            "Check provider configuration and API key validity. "
+            "Consult provider documentation for error details."
+        ),
+        request_id=request_id,
+    )
+
+
+def ai_context_too_large_error(
+    context_tokens: int,
+    max_tokens: int,
+    *,
+    provider_id: Optional[str] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for when context exceeds model limits.
+
+    Use when the prompt/context size exceeds the AI model's token limit.
+
+    Args:
+        context_tokens: Number of tokens in the attempted context.
+        max_tokens: Maximum tokens allowed by the model.
+        provider_id: The provider that rejected the context.
+        remediation: Guidance on how to reduce context size.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> ai_context_too_large_error(150000, 128000, provider_id="gemini")
+    """
+    data: Dict[str, Any] = {
+        "context_tokens": context_tokens,
+        "max_tokens": max_tokens,
+        "overflow_tokens": context_tokens - max_tokens,
+    }
+    if provider_id:
+        data["provider_id"] = provider_id
+
+    return error_response(
+        f"Context size ({context_tokens} tokens) exceeds limit ({max_tokens} tokens)",
+        error_code=ErrorCode.AI_CONTEXT_TOO_LARGE,
+        error_type=ErrorType.AI_PROVIDER,
+        data=data,
+        remediation=remediation
+        or (
+            "Reduce context size by: excluding large files, using incremental mode, "
+            "or reviewing only specific tasks/phases instead of the full spec."
+        ),
+        request_id=request_id,
+    )
+
+
+def ai_prompt_not_found_error(
+    prompt_id: str,
+    *,
+    available_prompts: Optional[Sequence[str]] = None,
+    workflow: Optional[str] = None,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for when a prompt template is not found.
+
+    Use when a requested prompt ID doesn't exist in the prompt registry.
+
+    Args:
+        prompt_id: The prompt ID that was not found.
+        available_prompts: List of valid prompt IDs for the workflow.
+        workflow: The workflow context (e.g., "plan_review", "fidelity_review").
+        remediation: Guidance on how to find the correct prompt ID.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> ai_prompt_not_found_error(
+        ...     "INVALID_PROMPT",
+        ...     available_prompts=["PLAN_REVIEW_FULL_V1", "PLAN_REVIEW_QUICK_V1"],
+        ...     workflow="plan_review",
+        ... )
+    """
+    data: Dict[str, Any] = {"prompt_id": prompt_id}
+    if available_prompts:
+        data["available_prompts"] = list(available_prompts)
+    if workflow:
+        data["workflow"] = workflow
+
+    available_str = ""
+    if available_prompts:
+        available_str = f" Available: {', '.join(available_prompts[:5])}"
+        if len(available_prompts) > 5:
+            available_str += f" (and {len(available_prompts) - 5} more)"
+
+    return error_response(
+        f"Prompt '{prompt_id}' not found.{available_str}",
+        error_code=ErrorCode.AI_PROMPT_NOT_FOUND,
+        error_type=ErrorType.NOT_FOUND,
+        data=data,
+        remediation=remediation
+        or (
+            "Use a valid prompt ID from the workflow's prompt builder. "
+            "Call list_prompts() to see available templates."
+        ),
+        request_id=request_id,
+    )
+
+
+def ai_cache_stale_error(
+    cache_key: str,
+    cache_age_seconds: int,
+    max_age_seconds: int,
+    *,
+    remediation: Optional[str] = None,
+    request_id: Optional[str] = None,
+) -> ToolResponse:
+    """Create an error response for when cached AI result is stale.
+
+    Use when a cached consultation result has expired and needs refresh.
+
+    Args:
+        cache_key: Identifier for the cached item.
+        cache_age_seconds: Age of the cached result in seconds.
+        max_age_seconds: Maximum allowed age for cached results.
+        remediation: Guidance on how to refresh the cache.
+        request_id: Correlation identifier.
+
+    Example:
+        >>> ai_cache_stale_error(
+        ...     "plan_review:spec-001:full",
+        ...     cache_age_seconds=7200,
+        ...     max_age_seconds=3600,
+        ... )
+    """
+    return error_response(
+        f"Cached result for '{cache_key}' is stale ({cache_age_seconds}s > {max_age_seconds}s)",
+        error_code=ErrorCode.AI_CACHE_STALE,
+        error_type=ErrorType.AI_PROVIDER,
+        data={
+            "cache_key": cache_key,
+            "cache_age_seconds": cache_age_seconds,
+            "max_age_seconds": max_age_seconds,
+        },
+        remediation=remediation
+        or (
+            "Re-run the consultation to refresh cached results, "
+            "or use --no-cache to bypass the cache."
+        ),
+        request_id=request_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Error Message Sanitization
+# ---------------------------------------------------------------------------
+
+
+try:
+    from pydantic import BaseModel, Field
+    PYDANTIC_AVAILABLE = True
+except ImportError:
+    PYDANTIC_AVAILABLE = False
+
+
+def sanitize_error_message(
+    exc: Exception,
+    context: str = "",
+    include_type: bool = False,
+) -> str:
+    """
+    Convert exception to user-safe message without internal details.
+
+    Logs full exception server-side for debugging per MCP best practices:
+    - "Never expose internal details" (07-error-semantics.md:16)
+    - "Log full details server-side" (07-error-semantics.md:23)
+
+    Args:
+        exc: The exception to sanitize
+        context: Optional context for logging (e.g., "spec validation")
+        include_type: Whether to include exception type name in message
+
+    Returns:
+        User-safe error message without file paths, stack traces, or internal state
+    """
+    # Log full details server-side for debugging
+    if context:
+        logger.debug(f"Error in {context}: {exc}", exc_info=True)
+    else:
+        logger.debug(f"Error: {exc}", exc_info=True)
+
+    # Map known exception types to safe messages
+    type_name = type(exc).__name__
+
+    if isinstance(exc, FileNotFoundError):
+        return "Required file or resource not found"
+    if isinstance(exc, json.JSONDecodeError):
+        return "Invalid JSON format"
+    if isinstance(exc, subprocess.TimeoutExpired):
+        timeout = getattr(exc, "timeout", "unknown")
+        return f"Operation timed out after {timeout} seconds"
+    if isinstance(exc, PermissionError):
+        return "Permission denied for requested operation"
+    if isinstance(exc, ValueError):
+        suffix = f" ({type_name})" if include_type else ""
+        return f"Invalid value provided{suffix}"
+    if isinstance(exc, KeyError):
+        return "Required configuration key not found"
+    if isinstance(exc, ConnectionError):
+        return "Connection failed - service may be unavailable"
+    if isinstance(exc, OSError):
+        return "System I/O error occurred"
+
+    # Generic fallback - don't expose exception message
+    suffix = f" ({type_name})" if include_type else ""
+    return f"An internal error occurred{suffix}"
+
+
+# ---------------------------------------------------------------------------
+# Batch Operation Response Schemas (Pydantic)
+# ---------------------------------------------------------------------------
+# These schemas provide type-safe definitions for batch operation responses.
+# They ensure contract stability and enable validation of batch operation data.
+
+
+if PYDANTIC_AVAILABLE:
+
+    class DependencyNode(BaseModel):
+        """A node in the dependency graph representing a task."""
+
+        id: str = Field(..., description="Task identifier")
+        title: str = Field(default="", description="Task title")
+        status: str = Field(default="", description="Task status")
+        file_path: Optional[str] = Field(
+            default=None, description="File path associated with the task"
+        )
+        is_target: bool = Field(
+            default=False, description="Whether this is a target task in the batch"
+        )
+
+    class DependencyEdge(BaseModel):
+        """An edge in the dependency graph representing a dependency relationship."""
+
+        from_id: str = Field(..., alias="from", description="Source task ID")
+        to_id: str = Field(..., alias="to", description="Target task ID")
+        edge_type: str = Field(
+            default="blocks", alias="type", description="Type of dependency (blocks)"
+        )
+
+        model_config = {"populate_by_name": True}
+
+    class DependencyGraph(BaseModel):
+        """Dependency graph structure for batch tasks.
+
+        Contains nodes (tasks) and edges (dependency relationships) to visualize
+        task dependencies for parallel execution planning.
+        """
+
+        nodes: list[DependencyNode] = Field(
+            default_factory=list, description="Task nodes in the graph"
+        )
+        edges: list[DependencyEdge] = Field(
+            default_factory=list, description="Dependency edges between tasks"
+        )
+
+    class BatchTaskDependencies(BaseModel):
+        """Dependency status for a task in a batch."""
+
+        task_id: str = Field(..., description="Task identifier")
+        can_start: bool = Field(
+            default=True, description="Whether the task can be started"
+        )
+        blocked_by: list[str] = Field(
+            default_factory=list, description="IDs of tasks blocking this one"
+        )
+        soft_depends: list[str] = Field(
+            default_factory=list, description="IDs of soft dependencies"
+        )
+        blocks: list[str] = Field(
+            default_factory=list, description="IDs of tasks this one blocks"
+        )
+
+    class BatchTaskContext(BaseModel):
+        """Context for a single task in a batch prepare response.
+
+        Contains all information needed to execute a task in parallel with others.
+        """
+
+        task_id: str = Field(..., description="Unique task identifier")
+        title: str = Field(default="", description="Task title")
+        task_type: str = Field(
+            default="task", alias="type", description="Task type (task, subtask, verify)"
+        )
+        status: str = Field(default="pending", description="Current task status")
+        metadata: Dict[str, Any] = Field(
+            default_factory=dict,
+            description="Task metadata including file_path, description, etc.",
+        )
+        dependencies: Optional[BatchTaskDependencies] = Field(
+            default=None, description="Dependency status for the task"
+        )
+        phase: Optional[Dict[str, Any]] = Field(
+            default=None, description="Phase context (id, title, progress)"
+        )
+        parent: Optional[Dict[str, Any]] = Field(
+            default=None, description="Parent task context (id, title, position_label)"
+        )
+
+        model_config = {"populate_by_name": True}
+
+    class StaleTaskInfo(BaseModel):
+        """Information about a stale in_progress task."""
+
+        task_id: str = Field(..., description="Task identifier")
+        title: str = Field(default="", description="Task title")
+
+    class BatchPrepareResponse(BaseModel):
+        """Response schema for prepare_batch_context operation.
+
+        Contains independent tasks that can be executed in parallel along with
+        context, dependency information, and warnings.
+        """
+
+        tasks: list[BatchTaskContext] = Field(
+            default_factory=list, description="Tasks ready for parallel execution"
+        )
+        task_count: int = Field(default=0, description="Number of tasks in the batch")
+        spec_complete: bool = Field(
+            default=False, description="Whether the spec has no remaining tasks"
+        )
+        all_blocked: bool = Field(
+            default=False, description="Whether all remaining tasks are blocked"
+        )
+        warnings: list[str] = Field(
+            default_factory=list, description="Non-fatal warnings about the batch"
+        )
+        stale_tasks: list[StaleTaskInfo] = Field(
+            default_factory=list, description="In-progress tasks exceeding time threshold"
+        )
+        dependency_graph: DependencyGraph = Field(
+            default_factory=DependencyGraph,
+            description="Dependency graph for batch tasks",
+        )
+        token_estimate: Optional[int] = Field(
+            default=None, description="Estimated token count for the batch context"
+        )
+
+    class BatchStartResponse(BaseModel):
+        """Response schema for start_batch operation.
+
+        Confirms which tasks were atomically started and when.
+        """
+
+        started: list[str] = Field(
+            default_factory=list, description="IDs of tasks successfully started"
+        )
+        started_count: int = Field(
+            default=0, description="Number of tasks started"
+        )
+        started_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when tasks were started"
+        )
+        errors: Optional[list[str]] = Field(
+            default=None, description="Validation errors if operation failed"
+        )
+
+    class BatchTaskCompletion(BaseModel):
+        """Input schema for a single task completion in complete_batch.
+
+        Used to specify outcome for each task being completed.
+        """
+
+        task_id: str = Field(..., description="Task identifier to complete")
+        success: bool = Field(
+            ..., description="True if task succeeded, False if failed"
+        )
+        completion_note: str = Field(
+            default="", description="Note describing what was accomplished or why it failed"
+        )
+
+    class BatchTaskResult(BaseModel):
+        """Result for a single task in the complete_batch response."""
+
+        status: str = Field(
+            ..., description="Result status: completed, failed, skipped, error"
+        )
+        completed_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when completed (if successful)"
+        )
+        failed_at: Optional[str] = Field(
+            default=None, description="ISO timestamp when failed (if unsuccessful)"
+        )
+        retry_count: Optional[int] = Field(
+            default=None, description="Updated retry count (if failed)"
+        )
+        error: Optional[str] = Field(
+            default=None, description="Error message (if status is error or skipped)"
+        )
+
+    class BatchCompleteResponse(BaseModel):
+        """Response schema for complete_batch operation.
+
+        Contains per-task results and summary counts for the batch completion.
+        """
+
+        results: Dict[str, BatchTaskResult] = Field(
+            default_factory=dict,
+            description="Per-task results keyed by task_id",
+        )
+        completed_count: int = Field(
+            default=0, description="Number of tasks successfully completed"
+        )
+        failed_count: int = Field(
+            default=0, description="Number of tasks that failed"
+        )
+        total_processed: int = Field(
+            default=0, description="Total number of completions processed"
+        )
+
+    # Export Pydantic models
+    __all_pydantic__ = [
+        "DependencyNode",
+        "DependencyEdge",
+        "DependencyGraph",
+        "BatchTaskDependencies",
+        "BatchTaskContext",
+        "StaleTaskInfo",
+        "BatchPrepareResponse",
+        "BatchStartResponse",
+        "BatchTaskCompletion",
+        "BatchTaskResult",
+        "BatchCompleteResponse",
+    ]
+
+else:
+    # Pydantic not available - provide None placeholders
+    DependencyNode = None  # type: ignore[misc,assignment]
+    DependencyEdge = None  # type: ignore[misc,assignment]
+    DependencyGraph = None  # type: ignore[misc,assignment]
+    BatchTaskDependencies = None  # type: ignore[misc,assignment]
+    BatchTaskContext = None  # type: ignore[misc,assignment]
+    StaleTaskInfo = None  # type: ignore[misc,assignment]
+    BatchPrepareResponse = None  # type: ignore[misc,assignment]
+    BatchStartResponse = None  # type: ignore[misc,assignment]
+    BatchTaskCompletion = None  # type: ignore[misc,assignment]
+    BatchTaskResult = None  # type: ignore[misc,assignment]
+    BatchCompleteResponse = None  # type: ignore[misc,assignment]
+    __all_pydantic__ = []