Nayana-R-Gowda
diff --git a/‎docs/docs/using/plugins/index.md‎
Lines changed: 119 additions & 1 deletion b/‎docs/docs/using/plugins/index.md‎
Lines changed: 119 additions & 1 deletion
diff --git a/‎mcpgateway/main.py‎
Lines changed: 85 additions & 3 deletions b/‎mcpgateway/main.py‎
Lines changed: 85 additions & 3 deletions
@@ -243,7 +243,7 @@ Each plugin can operate in one of four modes:
 | Mode | Description | Use Case |
 |------|-------------|----------|
 | **enforce** | Blocks requests on policy violations and plugin errors | Production guardrails |
-| **enforce_ignore_errors** | Blocks requests on policy violations; logs errors and continues | Guardrails with fault tolerance |
+| **enforce_ignore_errors** | Blocks requests on policy violations but only logs errors | Production guardrails |
 | **permissive** | Logs violations but allows requests | Testing and monitoring |
 | **disabled** | Plugin loaded but not executed | Temporary deactivation |
 
@@ -308,6 +308,44 @@ The plugin framework provides comprehensive hook coverage across the entire MCP
 | `federation_pre_sync` | Gateway federation validation and filtering | v0.8.0 |
 | `federation_post_sync` | Post-federation data processing and reconciliation | v0.8.0 |
 
+### Prompt Hooks Details
+
+The prompt hooks allow plugins to intercept and modify prompt retrieval and rendering:
+
+- **`prompt_pre_fetch`**: Receives the prompt name and arguments before prompt template retrieval.  Can modify the arguments.
+- **`prompt_post_fetch`**: Receives the completed prompt after rendering.  Can modify the prompt text or block it from being returned.
+
+Example Use Cases:
+- Detect prompt injection attacks
+- Sanitize or anonymize prompts
+- Search and replace
+
+#### Prompt Hook Payloads
+
+**PromptPrehookPayload**: Payload for prompt pre-fetch hooks.
+
+```python
+class PromptPrehookPayload(BaseModel):
+    name: str                                    # Prompt template name
+    args: Optional[dict[str, str]] = Field(default_factory=dict)  # Template arguments
+```
+
+**Example**:
+```python
+payload = PromptPrehookPayload(
+    name="user_greeting",
+    args={"user_name": "Alice", "time_of_day": "morning"}
+)
+```
+
+**PromptPosthookPayload**: Payload for prompt post-fetch hooks.
+
+```python
+class PromptPosthookPayload(BaseModel):
+    name: str                                    # Prompt name
+    result: PromptResult                         # Rendered prompt result
+```
+
 ### Tool Hooks Details
 
 The tool hooks enable plugins to intercept and modify tool invocations:
@@ -322,6 +360,42 @@ Example use cases:
 - Input validation and sanitization
 - Output filtering and transformation
 
+#### Tool Hook Payloads
+
+**ToolPreInvokePayload**: Payload for tool pre-invoke hooks.
+
+```python
+class ToolPreInvokePayload(BaseModel):
+    name: str                                    # Tool name
+    args: Optional[dict[str, Any]] = Field(default_factory=dict)  # Tool arguments
+    headers: Optional[HttpHeaderPayload] = None  # HTTP pass-through headers
+```
+
+**ToolPostInvokePayload**: Payload for tool post-invoke hooks.
+
+```python
+class ToolPostInvokePayload(BaseModel):
+    name: str                                    # Tool name
+    result: Any                                  # Tool execution result
+```
+
+The associated `HttpHeaderPayload` object for the `ToolPreInvokePayload` is as follows:
+
+Special payload for HTTP header manipulation.
+
+```python
+class HttpHeaderPayload(RootModel[dict[str, str]]):
+    # Provides dictionary-like access to HTTP headers
+    # Supports: __iter__, __getitem__, __setitem__, __len__
+```
+
+**Usage**:
+```python
+headers = HttpHeaderPayload({"Authorization": "Bearer token", "Content-Type": "application/json"})
+headers["X-Custom-Header"] = "custom_value"
+auth_header = headers["Authorization"]
+```
+
 ### Resource Hooks Details
 
 The resource hooks enable plugins to intercept and modify resource fetching:
@@ -337,6 +411,24 @@ Example use cases:
 - Content transformation and filtering
 - Resource caching metadata
 
+#### Resource Hook Payloads
+
+**ResourcePreFetchPayload**: Payload for resource pre-fetch hooks.
+
+```python
+class ResourcePreFetchPayload(BaseModel):
+    uri: str                                     # Resource URI
+    metadata: Optional[dict[str, Any]] = Field(default_factory=dict)  # Request metadata
+```
+
+**ResourcePostFetchPayload**: Payload for resource post-fetch hooks.
+
+```python
+class ResourcePostFetchPayload(BaseModel):
+    uri: str                                     # Resource URI
+    content: Any                                 # Fetched resource content
+```
+
 Planned hooks (not yet implemented):
 
 - `server_pre_register` / `server_post_register` - Server validation
@@ -611,6 +703,32 @@ async def prompt_post_fetch(self, payload, context):
     return PromptPosthookResult()
 ```
 
+#### Tool and Gateway Metadata
+
+Currently, the tool pre/post hooks have access to tool and gateway metadata through the global context metadata dictionary.  They are accessible as follows:
+
+It can be accessed inside of the tool hooks through:
+
+```python
+from mcpgateway.plugins.framework.constants import GATEWAY_METADATA, TOOL_METADATA
+
+tool_meta = context.global_context.metadata[TOOL_METADATA]
+assert tool_meta.original_name == "test_tool"
+assert tool_meta.url.host == "example.com"
+assert tool_meta.integration_type == "REST" or tool_meta.integration_type == "MCP"
+```
+
+Note, if the integration type is `MCP` the gateway information may also be available as follows.
+
+```python
+gateway_meta = context.global_context.metadata[GATEWAY_METADATA]
+assert gateway_meta.name == "test_gateway"
+assert gateway_meta.transport == "sse"
+assert gateway_meta.url.host == "example.com"
+```
+
+Metadata for other entities such as prompts and resources will be added in future versions of the gateway.
+
 ### External Service Plugin Example
 
 ```python
 
@@ -69,7 +69,7 @@
 from mcpgateway.middleware.token_scoping import token_scoping_middleware
 from mcpgateway.models import InitializeResult, ListResourceTemplatesResult, LogLevel, Root
 from mcpgateway.observability import init_telemetry
-from mcpgateway.plugins.framework import PluginManager, PluginViolationError
+from mcpgateway.plugins.framework import PluginError, PluginManager, PluginViolationError
 from mcpgateway.routers.well_known import router as well_known_router
 from mcpgateway.schemas import (
     A2AAgentCreate,
@@ -494,6 +494,81 @@ async def database_exception_handler(_request: Request, exc: IntegrityError):
     return JSONResponse(status_code=409, content=ErrorFormatter.format_database_error(exc))
 
 
+@app.exception_handler(PluginViolationError)
+async def plugin_violation_exception_handler(_request: Request, exc: PluginViolationError):
+    """Handle plugins violations globally.
+
+    Intercepts PluginViolationError exceptions (e.g., OPA policy violation) and returns a properly formatted JSON error response.
+    This provides consistent error handling for plugin violation across the entire application.
+
+    Args:
+        _request: The FastAPI request object that triggered the database error.
+                  (Unused but required by FastAPI's exception handler interface)
+        exc: The PluginViolationError exception containing constraint
+             violation details.
+
+    Returns:
+        JSONResponse: A 403 response with access forbidden.
+
+    Examples:
+        >>> from mcpgateway.plugins.framework import PluginViolationError
+        >>> from mcpgateway.plugins.framework.models import PluginViolation
+        >>> from fastapi import Request
+        >>> import asyncio
+        >>>
+        >>> # Create a mock integrity error
+        >>> mock_error = PluginViolationError(message="plugin violation",violation = PluginViolation(
+        ...     reason="Invalid input",
+        ...     description="The input contains prohibited content",
+        ...     code="PROHIBITED_CONTENT",
+        ...     details={"field": "message", "value": "test"}
+        ... ))
+        >>> result = asyncio.run(plugin_violation_exception_handler(None, mock_error))
+        >>> result.status_code
+        403
+    """
+    policy_violation = exc.violation.model_dump() if exc.violation else {}
+    policy_violation["message"] = exc.message
+    return JSONResponse(status_code=403, content=policy_violation)
+
+
+@app.exception_handler(PluginError)
+async def plugin_exception_handler(_request: Request, exc: PluginError):
+    """Handle plugins errors globally.
+
+    Intercepts PluginError exceptions and returns a properly formatted JSON error response.
+    This provides consistent error handling for plugin error across the entire application.
+
+    Args:
+        _request: The FastAPI request object that triggered the database error.
+                  (Unused but required by FastAPI's exception handler interface)
+        exc: The PluginError exception containing constraint
+             violation details.
+
+    Returns:
+        JSONResponse: A 500 response with internal server error.
+
+    Examples:
+        >>> from mcpgateway.plugins.framework import PluginViolationError
+        >>> from mcpgateway.plugins.framework.models import PluginErrorModel
+        >>> from fastapi import Request
+        >>> import asyncio
+        >>>
+        >>> # Create a mock integrity error
+        >>> mock_error = PluginError(error = PluginErrorModel(
+        ...     message="plugin error",
+        ...     code="timeout",
+        ...     plugin_name="abc",
+        ...     details={"field": "message", "value": "test"}
+        ... ))
+        >>> result = asyncio.run(plugin_exception_handler(None, mock_error))
+        >>> result.status_code
+        500
+    """
+    error_obj = exc.error.model_dump() if exc.error else {}
+    return JSONResponse(status_code=500, content=error_obj)
+
+
 class DocsAuthMiddleware(BaseHTTPMiddleware):
     """
     Middleware to protect FastAPI's auto-generated documentation routes
@@ -3214,6 +3289,10 @@ async def handle_rpc(request: Request, db: Session = Depends(get_db), user=Depen
 
     Returns:
         Response with the RPC result or error.
+
+    Raises:
+        PluginError: If encounters issue with plugin
+        PluginViolationError: If plugin violated the request. Example - In case of OPA plugin, if the request is denied by policy.
     """
     try:
         # Extract user identifier from either RBAC user object or JWT payload
@@ -3324,13 +3403,14 @@ async def handle_rpc(request: Request, db: Session = Depends(get_db), user=Depen
         else:
             # Backward compatibility: Try to invoke as a tool directly
             # This allows both old format (method=tool_name) and new format (method=tools/call)
+            # Standard
             headers = {k.lower(): v for k, v in request.headers.items()}
             try:
                 result = await tool_service.invoke_tool(db=db, name=method, arguments=params, request_headers=headers)
                 if hasattr(result, "model_dump"):
                     result = result.model_dump(by_alias=True, exclude_none=True)
-            except PluginViolationError:
-                return JSONResponse(status_code=403, content={"detail": "policy_deny"})
+            except (PluginError, PluginViolationError):
+                raise
             except (ValueError, Exception):
                 # If not a tool, try forwarding to gateway
                 try:
@@ -3343,6 +3423,8 @@ async def handle_rpc(request: Request, db: Session = Depends(get_db), user=Depen
 
         return {"jsonrpc": "2.0", "result": result, "id": req_id}
 
+    except (PluginError, PluginViolationError):
+        raise
     except JSONRPCError as e:
         error = e.to_dict()
         return {"jsonrpc": "2.0", "error": error["error"], "id": req_id}