adloop 0.35.1__tar.gz → 0.37.0__tar.gz

{adloop-0.35.1 → adloop-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.35.1
+Version: 0.37.0
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose
@@ -131,6 +131,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_negative_keyword_list_keywords` | List the keywords inside a specific shared negative keyword list |
 | `get_negative_keyword_list_campaigns` | List which campaigns a shared negative keyword list is attached to |
 | `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
+| `get_recommendation_subscriptions` | Which recommendation types Google applies automatically (auto-apply), with status and last change; flags any that are on |
 | `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
 | `get_pmax_assets` | Per-asset details for PMax — field type, serving status, content |
 | `get_asset_group_signals` | A PMax asset group's search themes and audience signal, plus the audiences available for it |
@@ -148,6 +149,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_brand_list_brands` | List the brands inside a list, with the Commercial KG MID and the criterion ID for removals |
 | `get_brand_list_campaigns` | Which campaigns a brand list is attached to, and whether each attachment excludes or targets |
 | `get_ai_max_settings` | AI Max knobs per campaign and ad group — `enable_ai_max`, `bundling_required`, the full `asset_automation_settings` list and each ad group's `disable_search_term_matching` |
+| `get_campaign_settings` | One flat record per Search campaign — networks, location option, campaign-level broad match, bidding, budget, URL options and AI Max — with the settings that widen reach flagged |
 | `get_custom_conversion_goals` | Custom conversion goals with their actions, plus one campaign's goal config |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
@@ -296,12 +298,12 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 
 | Tool | What It Does |
 |------|-------------|
-| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
+| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, the location option (presence vs presence or interest), campaign URL options (tracking template, final URL suffix, custom parameters), and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
 | `draft_shopping_campaign` | Create a Standard Shopping campaign for a linked Merchant Center feed — budget, campaign (PAUSED), product ad group, Shopping ad and an "All products" group in one atomic request. Manual CPC, Maximize clicks or target ROAS. |
 | `draft_asset_group_assets` | Add and remove Performance Max assets (text, images incl. uploads, YouTube videos) in one change, so replacing an asset never drops a group below Google's minimums |
 | `draft_asset_group_signals` | Add search themes or set the audience signal of a PMax asset group |
 | `draft_pmax_product_exclusions` | Exclude products from a retail PMax asset group by item id, brand or custom label |
-| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
+| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, the location option, campaign URL options, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
 | `draft_ad_group` | Create a paused SEARCH_STANDARD ad group inside an existing campaign, with optional MANUAL_CPC `max_cpc`. |
 | `update_ad_group` | Update an ad group name and/or MANUAL_CPC `max_cpc`. Use `pause_entity` / `enable_entity` for ad-group status changes. |
 | `draft_responsive_search_ad` | Create RSA preview (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). Warns if headline/description count is below best practice. |
@@ -334,6 +336,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_update_custom_conversion_goal` | Rename a custom conversion goal and/or replace its action list (list replace, not append) |
 | `draft_assign_custom_conversion_goal` | Point a campaign at a custom conversion goal (`goal_config_level = CAMPAIGN`) |
 | `draft_clear_custom_conversion_goal` | Put a campaign back on the account-level goals (rollback) |
+| `draft_dismiss_recommendations` | Dismiss Google recommendations you won't take, so they stop reappearing (Google can show them again later) |
+| `draft_recommendation_subscriptions` | Pause auto-apply for recommendation types, so Google stops changing the account without a preview. Switching auto-apply back on stays in the Google Ads UI |
 | `pause_entity` | Pause a campaign, ad group, ad, keyword or PMax asset group |
 | `enable_entity` | Re-enable a paused entity |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |
@@ -523,8 +527,8 @@ adloop install-rules
 
 This writes a managed block to `~/.claude/CLAUDE.md` and copies the slash commands (prefixed `adloop-*`) into `~/.claude/commands/`. The block is delimited by sentinel comments so it's safe to run multiple times — re-running just refreshes the content. Two install modes:
 
-- **inline** (default) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable but adds ~10K tokens to every Claude Code session.
-- **lazy** (`adloop install-rules --lazy`) — small directive in `CLAUDE.md` pointing at `~/.claude/rules/adloop.md`. Cheaper baseline cost; the LLM reads the rules file only when AdLoop tools are in scope.
+- **inline** (default for `install-rules`) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable, but they load into every Claude Code session in every repository, about 30K tokens, whether AdLoop is connected or not.
+- **lazy** (`adloop install-rules --lazy`, and the default in `adloop init`) — a short directive in `CLAUDE.md` pointing at `~/.adloop/rules/adloop.md`. The LLM reads the rules file only when AdLoop tools are in scope, so sessions without AdLoop stay almost free. The file sits outside `~/.claude/` on purpose: Claude Code loads everything in `~/.claude/rules/` into every session.
 
 To refresh after upgrading AdLoop: `adloop update-rules`. To remove cleanly: `adloop uninstall-rules` — only the managed block and `adloop-*` commands are touched, never your own content.
 

{adloop-0.35.1 → adloop-0.37.0}/README.md

@@ -103,6 +103,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_negative_keyword_list_keywords` | List the keywords inside a specific shared negative keyword list |
 | `get_negative_keyword_list_campaigns` | List which campaigns a shared negative keyword list is attached to |
 | `get_recommendations` | Google's auto-generated recommendations with type, estimated impact, and campaign context |
+| `get_recommendation_subscriptions` | Which recommendation types Google applies automatically (auto-apply), with status and last change; flags any that are on |
 | `get_pmax_performance` | Performance Max campaign metrics with network breakdown + asset group ad strength |
 | `get_pmax_assets` | Per-asset details for PMax — field type, serving status, content |
 | `get_asset_group_signals` | A PMax asset group's search themes and audience signal, plus the audiences available for it |
@@ -120,6 +121,7 @@ The best features come from real workflows. If you're using AdLoop and find your
 | `get_brand_list_brands` | List the brands inside a list, with the Commercial KG MID and the criterion ID for removals |
 | `get_brand_list_campaigns` | Which campaigns a brand list is attached to, and whether each attachment excludes or targets |
 | `get_ai_max_settings` | AI Max knobs per campaign and ad group — `enable_ai_max`, `bundling_required`, the full `asset_automation_settings` list and each ad group's `disable_search_term_matching` |
+| `get_campaign_settings` | One flat record per Search campaign — networks, location option, campaign-level broad match, bidding, budget, URL options and AI Max — with the settings that widen reach flagged |
 | `get_custom_conversion_goals` | Custom conversion goals with their actions, plus one campaign's goal config |
 | `run_gaql` | Arbitrary GAQL queries for anything else |
 
@@ -268,12 +270,12 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 
 | Tool | What It Does |
 |------|-------------|
-| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
+| `draft_campaign` | Create a full campaign structure — budget + campaign (PAUSED) + ad group + optional keywords. Supports Search partners, display expansion, the location option (presence vs presence or interest), campaign URL options (tracking template, final URL suffix, custom parameters), and `max_cpc` for either MANUAL_CPC initial ad-group bids or TARGET_SPEND (Maximize Clicks) CPC caps. |
 | `draft_shopping_campaign` | Create a Standard Shopping campaign for a linked Merchant Center feed — budget, campaign (PAUSED), product ad group, Shopping ad and an "All products" group in one atomic request. Manual CPC, Maximize clicks or target ROAS. |
 | `draft_asset_group_assets` | Add and remove Performance Max assets (text, images incl. uploads, YouTube videos) in one change, so replacing an asset never drops a group below Google's minimums |
 | `draft_asset_group_signals` | Add search themes or set the audience signal of a PMax asset group |
 | `draft_pmax_product_exclusions` | Exclude products from a retail PMax asset group by item id, brand or custom label |
-| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
+| `update_campaign` | Modify existing campaign settings — bidding, budget, geo/language targeting, the location option, campaign URL options, Search partners, display expansion, and TARGET_SPEND (Maximize Clicks) `max_cpc` caps. |
 | `draft_ad_group` | Create a paused SEARCH_STANDARD ad group inside an existing campaign, with optional MANUAL_CPC `max_cpc`. |
 | `update_ad_group` | Update an ad group name and/or MANUAL_CPC `max_cpc`. Use `pause_entity` / `enable_entity` for ad-group status changes. |
 | `draft_responsive_search_ad` | Create RSA preview (3-15 headlines ≤30 chars, 2-4 descriptions ≤90 chars). Warns if headline/description count is below best practice. |
@@ -306,6 +308,8 @@ All write operations follow a **draft → preview → confirm** workflow. Nothin
 | `draft_update_custom_conversion_goal` | Rename a custom conversion goal and/or replace its action list (list replace, not append) |
 | `draft_assign_custom_conversion_goal` | Point a campaign at a custom conversion goal (`goal_config_level = CAMPAIGN`) |
 | `draft_clear_custom_conversion_goal` | Put a campaign back on the account-level goals (rollback) |
+| `draft_dismiss_recommendations` | Dismiss Google recommendations you won't take, so they stop reappearing (Google can show them again later) |
+| `draft_recommendation_subscriptions` | Pause auto-apply for recommendation types, so Google stops changing the account without a preview. Switching auto-apply back on stays in the Google Ads UI |
 | `pause_entity` | Pause a campaign, ad group, ad, keyword or PMax asset group |
 | `enable_entity` | Re-enable a paused entity |
 | `remove_entity` | Permanently remove an entity (irreversible — prefers pause). Supports keywords, negative keywords, ads, ad groups, campaigns. |
@@ -495,8 +499,8 @@ adloop install-rules
 
 This writes a managed block to `~/.claude/CLAUDE.md` and copies the slash commands (prefixed `adloop-*`) into `~/.claude/commands/`. The block is delimited by sentinel comments so it's safe to run multiple times — re-running just refreshes the content. Two install modes:
 
-- **inline** (default) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable but adds ~10K tokens to every Claude Code session.
-- **lazy** (`adloop install-rules --lazy`) — small directive in `CLAUDE.md` pointing at `~/.claude/rules/adloop.md`. Cheaper baseline cost; the LLM reads the rules file only when AdLoop tools are in scope.
+- **inline** (default for `install-rules`) — full rules embedded in `~/.claude/CLAUDE.md`. Reliable, but they load into every Claude Code session in every repository, about 30K tokens, whether AdLoop is connected or not.
+- **lazy** (`adloop install-rules --lazy`, and the default in `adloop init`) — a short directive in `CLAUDE.md` pointing at `~/.adloop/rules/adloop.md`. The LLM reads the rules file only when AdLoop tools are in scope, so sessions without AdLoop stay almost free. The file sits outside `~/.claude/` on purpose: Claude Code loads everything in `~/.claude/rules/` into every session.
 
 To refresh after upgrading AdLoop: `adloop update-rules`. To remove cleanly: `adloop uninstall-rules` — only the managed block and `adloop-*` commands are touched, never your own content.
 

{adloop-0.35.1 → adloop-0.37.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.35.1"
+version = "0.37.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.35.1 → adloop-0.37.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.35.1"
+version = "0.37.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

adloop-0.37.0/src/adloop/ads/campaign_settings.py

@@ -0,0 +1,222 @@
+"""One read for the settings that decide how far a Search campaign reaches.
+
+A recurring audit ("has Google switched anything back on?") otherwise needs
+``get_ai_max_settings`` plus hand-written GAQL for networks, location option,
+campaign-level broad match and URL options. Every field below was checked
+against the v25 ``campaign`` resource:
+
+    campaign.network_settings.target_google_search / target_search_network /
+        target_content_network / target_partner_search_network
+    campaign.geo_target_type_setting.positive_geo_target_type   PRESENCE_OR_INTEREST,
+                                                                SEARCH_INTEREST, PRESENCE
+    campaign.geo_target_type_setting.negative_geo_target_type   PRESENCE_OR_INTEREST, PRESENCE
+    campaign.keyword_match_type                                 BROAD, or unset
+    campaign.tracking_url_template, final_url_suffix, url_custom_parameters
+    campaign.bidding_strategy_type and the per-strategy targets
+    campaign_budget.amount_micros, explicitly_shared
+
+The AI Max half comes from ``ai_max.read_ai_max_state`` unchanged, so both tools
+always agree. Read-only: nothing here mutates.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+_SETTINGS_SELECT = """
+    SELECT campaign.id, campaign.name, campaign.status,
+           campaign.advertising_channel_type,
+           campaign.bidding_strategy_type, campaign.bidding_strategy,
+           campaign.target_spend.cpc_bid_ceiling_micros,
+           campaign.maximize_conversions.target_cpa_micros,
+           campaign.target_cpa.target_cpa_micros,
+           campaign.target_roas.target_roas,
+           campaign.maximize_conversion_value.target_roas,
+           campaign.network_settings.target_google_search,
+           campaign.network_settings.target_search_network,
+           campaign.network_settings.target_content_network,
+           campaign.geo_target_type_setting.positive_geo_target_type,
+           campaign.geo_target_type_setting.negative_geo_target_type,
+           campaign.keyword_match_type,
+           campaign.tracking_url_template, campaign.final_url_suffix,
+           campaign.url_custom_parameters,
+           campaign_budget.amount_micros, campaign_budget.explicitly_shared
+    FROM campaign
+    WHERE {where}
+    ORDER BY campaign.name
+"""
+
+_SEARCH_ONLY = "campaign.advertising_channel_type = 'SEARCH'"
+_WHERE_ALL = f"campaign.status != 'REMOVED' AND {_SEARCH_ONLY}"
+
+# Google's default; it also reaches people elsewhere who search *about* the
+# targeted locations.
+_WIDE_LOCATION_OPTIONS = {"PRESENCE_OR_INTEREST", "SEARCH_INTEREST"}
+
+
+def _money(micros: object) -> float | None:
+    """Micros to account currency; 0 or missing means "not set"."""
+    if not micros:
+        return None
+    return round(int(micros) / 1_000_000, 2)
+
+
+def _target_cpa(row: dict) -> float | None:
+    return _money(
+        row.get("campaign.target_cpa.target_cpa_micros")
+        or row.get("campaign.maximize_conversions.target_cpa_micros")
+    )
+
+
+def _target_roas(row: dict) -> float | None:
+    value = row.get("campaign.target_roas.target_roas") or row.get(
+        "campaign.maximize_conversion_value.target_roas"
+    )
+    return value or None
+
+
+def _custom_parameters(value: object) -> list[dict]:
+    if not isinstance(value, list):
+        return []
+    return [
+        {"key": item.get("key", ""), "value": item.get("value", "")}
+        for item in value
+        if isinstance(item, dict)
+    ]
+
+
+def _widening(campaign: dict) -> list[str]:
+    """The settings on this campaign that let ads reach beyond what was chosen."""
+    found: list[str] = []
+    if campaign["search_partners"]:
+        found.append("search partners on")
+    if campaign["display_network"]:
+        found.append("Display network on")
+    if campaign["location_option"] in _WIDE_LOCATION_OPTIONS:
+        found.append(f"location option {campaign['location_option']}")
+    if campaign["keyword_match_type"] == "BROAD":
+        found.append("campaign-level broad match on")
+    if campaign["enable_ai_max"]:
+        found.append("AI Max on")
+    for automation, status in campaign["asset_automation"].items():
+        if status == "OPTED_IN":
+            found.append(f"{automation} opted in")
+    return found
+
+
+def get_campaign_settings(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    campaign_id: str = "",
+) -> dict:
+    """Read-only, one flat record per Search campaign. See the module docstring."""
+    from adloop.ads.client import get_ads_client, normalize_customer_id
+    from adloop.ads.currency import get_currency_code
+
+    campaign_id = str(campaign_id or "").strip()
+    if campaign_id and not campaign_id.isdigit():
+        return {"error": "campaign_id must be a numeric ID"}
+
+    cid = normalize_customer_id(customer_id or config.ads.customer_id)
+    client = get_ads_client(config)
+    result = read_campaign_settings(client, cid, campaign_id=campaign_id)
+    result["currency"] = get_currency_code(config, cid)
+    return result
+
+
+def read_campaign_settings(client: object, cid: str, *, campaign_id: str = "") -> dict:
+    """Run both reads and merge them per campaign."""
+    from adloop.ads.ai_max import _search, read_ai_max_state
+
+    if campaign_id and not str(campaign_id).isdigit():
+        # The id goes into the query text; anything else must not reach GAQL.
+        raise ValueError("campaign_id must be a numeric ID")
+    # An explicit ID stays Search-only too: the AI Max and location settings
+    # read here don't apply to Performance Max or Display campaigns.
+    where = f"campaign.id = {campaign_id} AND {_SEARCH_ONLY}" if campaign_id else _WHERE_ALL
+    rows = _search(
+        client.get_service("GoogleAdsService"), cid, _SETTINGS_SELECT.format(where=where)
+    )
+    ai_max = {
+        c["campaign_id"]: c
+        for c in read_ai_max_state(client, cid, campaign_id=campaign_id)["campaigns"]
+    }
+
+    campaigns: list[dict] = []
+    for row in rows:
+        key = str(row.get("campaign.id", ""))
+        if not key or (campaign_id and key != str(campaign_id)):
+            continue
+        ai = ai_max.get(key, {})
+        campaign = {
+            "campaign_id": key,
+            "campaign_name": row.get("campaign.name"),
+            "status": row.get("campaign.status"),
+            "advertising_channel_type": row.get("campaign.advertising_channel_type"),
+            "bidding_strategy_type": row.get("campaign.bidding_strategy_type"),
+            "portfolio_bidding_strategy": row.get("campaign.bidding_strategy") or None,
+            "cpc_bid_ceiling": _money(
+                row.get("campaign.target_spend.cpc_bid_ceiling_micros")
+            ),
+            "target_cpa": _target_cpa(row),
+            "target_roas": _target_roas(row),
+            "daily_budget": _money(row.get("campaign_budget.amount_micros")),
+            "budget_shared": bool(row.get("campaign_budget.explicitly_shared")),
+            "google_search": bool(row.get("campaign.network_settings.target_google_search")),
+            "search_partners": bool(
+                row.get("campaign.network_settings.target_search_network")
+            ),
+            "display_network": bool(
+                row.get("campaign.network_settings.target_content_network")
+            ),
+            "location_option": row.get(
+                "campaign.geo_target_type_setting.positive_geo_target_type"
+            ),
+            "negative_location_option": row.get(
+                "campaign.geo_target_type_setting.negative_geo_target_type"
+            ),
+            "keyword_match_type": row.get("campaign.keyword_match_type"),
+            "tracking_url_template": row.get("campaign.tracking_url_template") or "",
+            "final_url_suffix": row.get("campaign.final_url_suffix") or "",
+            "url_custom_parameters": _custom_parameters(
+                row.get("campaign.url_custom_parameters")
+            ),
+            "enable_ai_max": bool(ai.get("enable_ai_max")),
+            "asset_automation": {
+                item["asset_automation_type"]: item.get("asset_automation_status", "")
+                for item in ai.get("asset_automation_settings", [])
+            },
+            # Search term matching only acts under AI Max; listing every ad
+            # group's default False otherwise would be noise.
+            "ad_groups_with_search_term_matching": [
+                g["ad_group_name"]
+                for g in ai.get("ad_groups", [])
+                if g.get("disable_search_term_matching") is False
+            ] if ai.get("enable_ai_max") else [],
+        }
+        campaign["widening_settings"] = _widening(campaign)
+        campaigns.append(campaign)
+
+    insights: list[str] = []
+    for campaign in campaigns:
+        if campaign["widening_settings"]:
+            insights.append(
+                f"{campaign['campaign_name']} ({campaign['campaign_id']}): "
+                + ", ".join(campaign["widening_settings"])
+                + ". These let the ads reach beyond the keywords and locations "
+                "chosen; confirm they are intended."
+            )
+    if campaigns and not insights:
+        insights.append("No setting that widens reach is on in any campaign returned.")
+    if not campaigns:
+        insights.append("No non-removed Search campaign matched.")
+
+    return {
+        "campaigns": campaigns,
+        "total_campaigns": len(campaigns),
+        "insights": insights,
+    }

{adloop-0.35.1 → adloop-0.37.0}/src/adloop/ads/read.py

@@ -843,6 +843,10 @@ def get_recommendations(
         pot_conversions = _round_metric(getattr(pot, "conversions", 0))
 
         entry = {
+            # The ID (last segment of the resource name) is what
+            # draft_dismiss_recommendations takes.
+            "recommendation.id": rec.resource_name.rsplit("/", 1)[-1],
+            "recommendation.resource_name": rec.resource_name,
             "recommendation.type": rec_type,
             "recommendation.campaign": rec.campaign,
             "recommendation.ad_group": rec.ad_group or "",

adloop-0.37.0/src/adloop/ads/recommendation_subscriptions.py

@@ -0,0 +1,202 @@
+"""Read and pause Google Ads auto-apply recommendation subscriptions.
+
+A subscription makes Google apply every new recommendation of one type
+without asking, so a change reaches the account with no preview. The v25 API
+(verified against the SDK):
+
+    recommendation_subscription  resource_name, type, status (ENABLED | PAUSED),
+                                 create_date_time, modify_date_time
+    RecommendationSubscriptionService.MutateRecommendationSubscription
+        MutateRecommendationSubscriptionRequest{customer_id, operations[],
+            partial_failure, validate_only, response_content_type}
+
+A type with no subscription row is not auto-applied. The write side can only
+set a subscription to PAUSED: re-enabling auto-apply is a decision for the
+Google Ads UI, because it lets Google change the account without a preview,
+which is what AdLoop's flow exists to prevent. Pausing reduces automation, so
+a single confirmation is enough. The request has ``validate_only``, so the dry
+run goes through the validate-only client like other Google Ads writes.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date, datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+OPERATION = "pause_recommendation_subscriptions"
+
+# A subscription modified this recently is reported as a change, not only as a
+# standing setting: someone (or something) turned it on or touched it lately.
+RECENT_DAYS = 30
+
+_TYPE_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+_QUERY = """
+    SELECT recommendation_subscription.resource_name,
+           recommendation_subscription.type,
+           recommendation_subscription.status,
+           recommendation_subscription.create_date_time,
+           recommendation_subscription.modify_date_time
+    FROM recommendation_subscription
+"""
+
+
+def _read(config: AdLoopConfig, customer_id: str) -> list[dict]:
+    from adloop.ads.gaql import execute_query
+
+    return [
+        {
+            "type": row.get("recommendation_subscription.type", ""),
+            "status": row.get("recommendation_subscription.status", ""),
+            "resource_name": row.get("recommendation_subscription.resource_name", ""),
+            "create_date_time": row.get("recommendation_subscription.create_date_time", ""),
+            "modify_date_time": row.get("recommendation_subscription.modify_date_time", ""),
+        }
+        for row in execute_query(config, customer_id, _QUERY)
+    ]
+
+
+def _day(value: str) -> date | None:
+    """``2026-10-27 09:14:03`` (account time zone) -> the date, or None."""
+    try:
+        return date.fromisoformat(str(value or "")[:10])
+    except ValueError:
+        return None
+
+
+def get_recommendation_subscriptions(
+    config: AdLoopConfig, *, customer_id: str = "", today: date | None = None
+) -> dict:
+    """Read-only: every auto-apply subscription with its status and dates."""
+    subscriptions = sorted(_read(config, customer_id), key=lambda s: s["type"])
+    enabled = [s for s in subscriptions if s["status"] == "ENABLED"]
+    today = today or datetime.now(timezone.utc).date()
+
+    insights: list[str] = []
+    if enabled:
+        insights.append(
+            f"{len(enabled)} recommendation type(s) auto-apply without a preview: "
+            + ", ".join(s["type"] for s in enabled)
+            + ". Google changes the account for these on its own. "
+            "draft_recommendation_subscriptions pauses them."
+        )
+    for sub in enabled:
+        modified = _day(sub["modify_date_time"])
+        if modified and (today - modified).days <= RECENT_DAYS:
+            insights.append(
+                f"{sub['type']} auto-apply was turned on or changed on "
+                f"{sub['modify_date_time']}, within the last {RECENT_DAYS} days. "
+                "Confirm that was intended."
+            )
+    if not enabled:
+        insights.append("No recommendation type is set to auto-apply.")
+
+    return {
+        "subscriptions": subscriptions,
+        "total_subscriptions": len(subscriptions),
+        "enabled_count": len(enabled),
+        "insights": insights,
+    }
+
+
+def draft_recommendation_subscriptions(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    recommendation_types: list[str] | None = None,
+) -> dict:
+    """Draft pausing auto-apply for recommendation types — returns PREVIEW.
+
+    Pausing is the only change this can make. Each type must have an ENABLED
+    subscription; a type with none, or one already paused, is refused by name
+    so the preview only lists what the apply will change.
+    """
+    from adloop.safety.guards import SafetyViolation, check_blocked_operation
+    from adloop.safety.preview import ChangePlan, store_plan
+
+    try:
+        check_blocked_operation(OPERATION, config.safety)
+    except SafetyViolation as e:
+        return {"error": str(e)}
+
+    types: list[str] = []
+    errors: list[str] = []
+    for raw in recommendation_types or []:
+        value = str(raw or "").strip().upper()
+        if not value:
+            continue
+        if not _TYPE_RE.match(value):
+            errors.append(f"'{raw}' is not a RecommendationType name")
+        elif value not in types:
+            types.append(value)
+    if not types and not errors:
+        errors.append("At least one recommendation type is required")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    current = {s["type"]: s for s in _read(config, customer_id)}
+    not_enabled = [t for t in types if current.get(t, {}).get("status") != "ENABLED"]
+    if not_enabled:
+        return {
+            "error": "Validation failed",
+            "details": [
+                "Not auto-applied in this account (no subscription, or already "
+                "paused): " + ", ".join(not_enabled)
+                + ". get_recommendation_subscriptions lists the subscriptions."
+            ],
+        }
+
+    subscriptions = [
+        {
+            "type": t,
+            "resource_name": current[t]["resource_name"],
+            "current_status": "ENABLED",
+            "status": "PAUSED",
+            "modify_date_time": current[t]["modify_date_time"],
+        }
+        for t in types
+    ]
+    plan = ChangePlan(
+        operation=OPERATION,
+        entity_type="recommendation_subscription",
+        entity_id=",".join(types),
+        customer_id=customer_id,
+        changes={
+            "subscriptions": subscriptions,
+            "count": len(subscriptions),
+            "note": (
+                "Pausing stops Google applying these recommendation types on its "
+                "own. Recommendations still appear in get_recommendations. "
+                "Re-enabling auto-apply is done in the Google Ads UI."
+            ),
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
+def _apply_pause_recommendation_subscriptions(
+    client: object, cid: str, changes: dict
+) -> dict:
+    """Set each planned subscription to PAUSED in one request."""
+    from google.protobuf import field_mask_pb2
+
+    service = client.get_service("RecommendationSubscriptionService")
+    request = client.get_type("MutateRecommendationSubscriptionRequest")
+    request.customer_id = cid
+    paused_status = client.enums.RecommendationSubscriptionStatusEnum.PAUSED
+    for sub in changes["subscriptions"]:
+        # Hard-coded: whatever a stored plan says, this path only pauses.
+        operation = client.get_type("RecommendationSubscriptionOperation")
+        operation.update.resource_name = sub["resource_name"]
+        operation.update.status = paused_status
+        operation.update_mask.CopyFrom(field_mask_pb2.FieldMask(paths=["status"]))
+        request.operations.append(operation)
+
+    response = service.mutate_recommendation_subscription(request=request)
+    paused = [result.resource_name for result in response.results]
+    return {"paused": paused, "paused_count": len(paused)}