enh: Partial Scope Grants & Granular Permissions

README.md

@@ -560,6 +560,21 @@ Read-only mode provides secure, restricted access by:
 - Automatically filtering out tools that require write permissions at startup
 - Allowing read operations: list, get, search, and export across all services
 
+**🔐 Granular Permissions**
+```bash
+# Per-service permission levels
+uv run main.py --permissions gmail:organize drive:readonly
+
+# Combine permissions with tier filtering
+uv run main.py --permissions gmail:send drive:full --tool-tier core
+```
+Granular permissions mode provides service-by-service scope control:
+- Format: `service:level` (one entry per service)
+- Gmail levels: `readonly`, `organize`, `drafts`, `send`, `full` (cumulative)
+- Other services currently support: `readonly`, `full`
+- `--permissions` and `--read-only` are mutually exclusive
+- With `--tool-tier`, only tier-matched tools are enabled and only services with matching tier tools are imported
+
 **★ Tool Tiers**
 ```bash
 uv run main.py --tool-tier core      # ● Essential tools only
@@ -738,6 +753,9 @@ uv run main.py --tool-tier complete                        # Enable all availabl
 uv run main.py --tools gmail drive --tool-tier core        # Core tools for specific services
 uv run main.py --tools gmail --tool-tier extended          # Extended Gmail functionality only
 uv run main.py --tools docs sheets --tool-tier complete    # Full access to Docs and Sheets
+
+# Combine tier selection with granular permission levels
+uv run main.py --permissions gmail:organize drive:full --tool-tier core
 ```
 
 ## 📋 Credential Configuration

auth/google_auth.py

@@ -495,6 +495,12 @@ def handle_auth_callback(
             )
             os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
 
+        # Allow partial scope grants without raising an exception.
+        # When users decline some scopes on Google's consent screen,
+        # oauthlib raises because the granted scopes differ from requested.
+        if "OAUTHLIB_RELAX_TOKEN_SCOPE" not in os.environ:
+            os.environ["OAUTHLIB_RELAX_TOKEN_SCOPE"] = "1"
+
         store = get_oauth21_session_store()
         parsed_response = urlparse(authorization_response)
         state_values = parse_qs(parsed_response.query).get("state")
@@ -522,6 +528,29 @@ def handle_auth_callback(
         credentials = flow.credentials
         logger.info("Successfully exchanged authorization code for tokens.")
 
+        # Handle partial OAuth grants: if the user declined some scopes on
+        # Google's consent screen, credentials.granted_scopes contains only
+        # what was actually authorized. Store those instead of the inflated
+        # requested scopes so that refresh() sends the correct scope set.
+        granted = getattr(credentials, "granted_scopes", None)
+        if granted and set(granted) != set(credentials.scopes or []):
+            logger.warning(
+                "Partial OAuth grant detected. Requested: %s, Granted: %s",
+                credentials.scopes,
+                granted,
+            )
+            credentials = Credentials(
+                token=credentials.token,
+                refresh_token=credentials.refresh_token,
+                id_token=getattr(credentials, "id_token", None),
+                token_uri=credentials.token_uri,
+                client_id=credentials.client_id,
+                client_secret=credentials.client_secret,
+                scopes=list(granted),
+                expiry=credentials.expiry,
+                quota_project_id=getattr(credentials, "quota_project_id", None),
+            )
+
         # Get user info to determine user_id (using email here)
         user_info = get_user_info(credentials)
         if not user_info or "email" not in user_info:

auth/permissions.py

@@ -0,0 +1,248 @@
+"""
+Granular per-service permission levels.
+
+Each service has named permission levels (cumulative), mapping to a list of
+OAuth scopes. The levels for a service are ordered from least to most
+permissive — requesting level N implicitly includes all scopes from levels < N.
+
+Usage:
+    --permissions gmail:organize drive:readonly
+
+Gmail levels: readonly, organize, drafts, send, full
+Other services: readonly, full (extensible by adding entries to SERVICE_PERMISSION_LEVELS)
+"""
+
+import logging
+from typing import Dict, List, Optional, Tuple
+
+from auth.scopes import (
+    GMAIL_READONLY_SCOPE,
+    GMAIL_LABELS_SCOPE,
+    GMAIL_MODIFY_SCOPE,
+    GMAIL_COMPOSE_SCOPE,
+    GMAIL_SEND_SCOPE,
+    GMAIL_SETTINGS_BASIC_SCOPE,
+    DRIVE_READONLY_SCOPE,
+    DRIVE_FILE_SCOPE,
+    DRIVE_SCOPE,
+    CALENDAR_READONLY_SCOPE,
+    CALENDAR_EVENTS_SCOPE,
+    CALENDAR_SCOPE,
+    DOCS_READONLY_SCOPE,
+    DOCS_WRITE_SCOPE,
+    SHEETS_READONLY_SCOPE,
+    SHEETS_WRITE_SCOPE,
+    CHAT_READONLY_SCOPE,
+    CHAT_WRITE_SCOPE,
+    CHAT_SPACES_SCOPE,
+    CHAT_SPACES_READONLY_SCOPE,
+    FORMS_BODY_SCOPE,
+    FORMS_BODY_READONLY_SCOPE,
+    FORMS_RESPONSES_READONLY_SCOPE,
+    SLIDES_SCOPE,
+    SLIDES_READONLY_SCOPE,
+    TASKS_SCOPE,
+    TASKS_READONLY_SCOPE,
+    CONTACTS_SCOPE,
+    CONTACTS_READONLY_SCOPE,
+    CUSTOM_SEARCH_SCOPE,
+    SCRIPT_PROJECTS_SCOPE,
+    SCRIPT_PROJECTS_READONLY_SCOPE,
+    SCRIPT_DEPLOYMENTS_SCOPE,
+    SCRIPT_DEPLOYMENTS_READONLY_SCOPE,
+    SCRIPT_PROCESSES_READONLY_SCOPE,
+    SCRIPT_METRICS_SCOPE,
+)
+
+logger = logging.getLogger(__name__)
+
+# Ordered permission levels per service.
+# Each entry is (level_name, [additional_scopes_at_this_level]).
+# Scopes are CUMULATIVE: level N includes all scopes from levels 0..N.
+SERVICE_PERMISSION_LEVELS: Dict[str, List[Tuple[str, List[str]]]] = {
+    "gmail": [
+        ("readonly", [GMAIL_READONLY_SCOPE]),
+        ("organize", [GMAIL_LABELS_SCOPE, GMAIL_MODIFY_SCOPE]),
+        ("drafts", [GMAIL_COMPOSE_SCOPE]),
+        ("send", [GMAIL_SEND_SCOPE]),
+        ("full", [GMAIL_SETTINGS_BASIC_SCOPE]),
+    ],
+    "drive": [
+        ("readonly", [DRIVE_READONLY_SCOPE]),
+        ("full", [DRIVE_SCOPE, DRIVE_FILE_SCOPE]),
+    ],
+    "calendar": [
+        ("readonly", [CALENDAR_READONLY_SCOPE]),
+        ("full", [CALENDAR_SCOPE, CALENDAR_EVENTS_SCOPE]),
+    ],
+    "docs": [
+        ("readonly", [DOCS_READONLY_SCOPE, DRIVE_READONLY_SCOPE]),
+        ("full", [DOCS_WRITE_SCOPE, DRIVE_READONLY_SCOPE, DRIVE_FILE_SCOPE]),
+    ],
+    "sheets": [
+        ("readonly", [SHEETS_READONLY_SCOPE, DRIVE_READONLY_SCOPE]),
+        ("full", [SHEETS_WRITE_SCOPE, DRIVE_READONLY_SCOPE]),
+    ],
+    "chat": [
+        ("readonly", [CHAT_READONLY_SCOPE, CHAT_SPACES_READONLY_SCOPE]),
+        ("full", [CHAT_WRITE_SCOPE, CHAT_SPACES_SCOPE]),
+    ],
+    "forms": [
+        ("readonly", [FORMS_BODY_READONLY_SCOPE, FORMS_RESPONSES_READONLY_SCOPE]),
+        ("full", [FORMS_BODY_SCOPE, FORMS_RESPONSES_READONLY_SCOPE]),
+    ],
+    "slides": [
+        ("readonly", [SLIDES_READONLY_SCOPE]),
+        ("full", [SLIDES_SCOPE]),
+    ],
+    "tasks": [
+        ("readonly", [TASKS_READONLY_SCOPE]),
+        ("full", [TASKS_SCOPE]),
+    ],
+    "contacts": [
+        ("readonly", [CONTACTS_READONLY_SCOPE]),
+        ("full", [CONTACTS_SCOPE]),
+    ],
+    "search": [
+        ("readonly", [CUSTOM_SEARCH_SCOPE]),
+        ("full", [CUSTOM_SEARCH_SCOPE]),
+    ],
+    "appscript": [
+        (
+            "readonly",
+            [
+                SCRIPT_PROJECTS_READONLY_SCOPE,
+                SCRIPT_DEPLOYMENTS_READONLY_SCOPE,
+                SCRIPT_PROCESSES_READONLY_SCOPE,
+                SCRIPT_METRICS_SCOPE,
+                DRIVE_READONLY_SCOPE,
+            ],
+        ),
+        (
+            "full",
+            [
+                SCRIPT_PROJECTS_SCOPE,
+                SCRIPT_DEPLOYMENTS_SCOPE,
+                SCRIPT_PROCESSES_READONLY_SCOPE,
+                SCRIPT_METRICS_SCOPE,
+                DRIVE_FILE_SCOPE,
+            ],
+        ),
+    ],
+}
+
+# Module-level state: parsed --permissions config
+# Dict mapping service_name -> level_name, e.g. {"gmail": "organize"}
+_PERMISSIONS: Optional[Dict[str, str]] = None
+
+
+def set_permissions(permissions: Dict[str, str]) -> None:
+    """Set granular permissions from parsed --permissions argument."""
+    global _PERMISSIONS
+    _PERMISSIONS = permissions
+    logger.info("Granular permissions set: %s", permissions)
+
+
+def get_permissions() -> Optional[Dict[str, str]]:
+    """Return current permissions dict, or None if not using granular mode."""
+    return _PERMISSIONS
+
+
+def is_permissions_mode() -> bool:
+    """Check if granular permissions mode is active."""
+    return _PERMISSIONS is not None
+
+
+def get_scopes_for_permission(service: str, level: str) -> List[str]:
+    """
+    Get cumulative scopes for a service at a given permission level.
+
+    Returns all scopes up to and including the named level.
+    Raises ValueError if service or level is unknown.
+    """
+    levels = SERVICE_PERMISSION_LEVELS.get(service)
+    if levels is None:
+        raise ValueError(f"Unknown service: '{service}'")
+
+    cumulative: List[str] = []
+    found = False
+    for level_name, level_scopes in levels:
+        cumulative.extend(level_scopes)
+        if level_name == level:
+            found = True
+            break
+
+    if not found:
+        valid = [name for name, _ in levels]
+        raise ValueError(
+            f"Unknown permission level '{level}' for service '{service}'. "
+            f"Valid levels: {valid}"
+        )
+
+    return list(set(cumulative))
+
+
+def get_all_permission_scopes() -> List[str]:
+    """
+    Get the combined scopes for all services at their configured permission levels.
+
+    Only meaningful when is_permissions_mode() is True.
+    """
+    if _PERMISSIONS is None:
+        return []
+
+    all_scopes: set = set()
+    for service, level in _PERMISSIONS.items():
+        all_scopes.update(get_scopes_for_permission(service, level))
+    return list(all_scopes)
+
+
+def get_allowed_scopes_set() -> Optional[set]:
+    """
+    Get the set of allowed scopes under permissions mode (for tool filtering).
+
+    Returns None if permissions mode is not active.
+    """
+    if _PERMISSIONS is None:
+        return None
+    return set(get_all_permission_scopes())
+
+
+def get_valid_levels(service: str) -> List[str]:
+    """Get valid permission level names for a service."""
+    levels = SERVICE_PERMISSION_LEVELS.get(service)
+    if levels is None:
+        return []
+    return [name for name, _ in levels]
+
+
+def parse_permissions_arg(permissions_list: List[str]) -> Dict[str, str]:
+    """
+    Parse --permissions arguments like ["gmail:organize", "drive:full"].
+
+    Returns dict mapping service -> level.
+    Raises ValueError on parse errors (unknown service, invalid level, bad format).
+    """
+    result: Dict[str, str] = {}
+    for entry in permissions_list:
+        if ":" not in entry:
+            raise ValueError(
+                f"Invalid permission format: '{entry}'. "
+                f"Expected 'service:level' (e.g., 'gmail:organize', 'drive:readonly')"
+            )
+        service, level = entry.split(":", 1)
+        if service in result:
+            raise ValueError(f"Duplicate service in permissions: '{service}'")
+        if service not in SERVICE_PERMISSION_LEVELS:
+            raise ValueError(
+                f"Unknown service: '{service}'. "
+                f"Valid services: {sorted(SERVICE_PERMISSION_LEVELS.keys())}"
+            )
+        valid = get_valid_levels(service)
+        if level not in valid:
+            raise ValueError(
+                f"Unknown level '{level}' for service '{service}'. "
+                f"Valid levels: {valid}"
+            )
+        result[service] = level
+    return result

auth/scopes.py

@@ -291,6 +291,24 @@ def get_scopes_for_tools(enabled_tools=None):
     Returns:
         List of unique scopes for the enabled tools plus base scopes.
     """
+    # Granular permissions mode overrides both full and read-only scope maps.
+    # Lazy import with guard to avoid circular dependency during module init
+    # (SCOPES = get_scopes_for_tools() runs at import time before auth.permissions
+    # is fully loaded, but permissions mode is never active at that point).
+    try:
+        from auth.permissions import is_permissions_mode, get_all_permission_scopes
+
+        if is_permissions_mode():
+            scopes = BASE_SCOPES.copy()
+            scopes.extend(get_all_permission_scopes())
+            logger.debug(
+                "Generated scopes from granular permissions: %d unique scopes",
+                len(set(scopes)),
+            )
+            return list(set(scopes))
+    except ImportError:
+        pass
+
     if enabled_tools is None:
         # Default behavior - return all scopes
         enabled_tools = TOOL_SCOPES_MAP.keys()