adloop 0.35.1__tar.gz → 0.36.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.35.1
+Version: 0.36.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
@@ -148,6 +148,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 |
 
@@ -334,6 +335,7 @@ 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) |
 | `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 +525,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.36.0}/README.md

@@ -120,6 +120,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 |
 
@@ -306,6 +307,7 @@ 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) |
 | `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 +497,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.36.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.35.1"
+version = "0.36.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.36.0}/pyproject.toml.orig

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

adloop-0.36.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.36.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.36.0/src/adloop/ads/recommendations.py

@@ -0,0 +1,210 @@
+"""Dismiss Google Ads recommendations.
+
+``get_recommendations`` (in ``ads/read.py``) lists the active ones; this module
+turns a chosen subset down. The v25 call (verified against the SDK):
+
+    RecommendationService.DismissRecommendation
+        DismissRecommendationRequest{customer_id, operations[], partial_failure}
+        DismissRecommendationOperation{resource_name}
+
+The request has **no** ``validate_only`` field, so a dry run cannot hand the
+exact call to Google the way other Google Ads writes do. Instead the dry run
+re-reads the account and checks that every planned recommendation is still
+active (``preflight``), the same approach the Reddit, Tag Manager and GA4
+writes use. The validate-only client still refuses the call outright, so this
+path can never dismiss anything during a dry run.
+
+Dismissing is mild: nothing in the account changes, and Google can show the
+recommendation again later. A single confirmation is enough.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+OPERATION = "dismiss_recommendations"
+
+# A recommendation ID is the last segment of its resource name. Google does not
+# document the alphabet, so accept what resource names can carry and nothing
+# that could break out of one.
+_ID_RE = re.compile(r"^[A-Za-z0-9_~=+-]+$")
+_RESOURCE_RE = re.compile(r"^customers/(\d+)/recommendations/([A-Za-z0-9_~=+-]+)$")
+
+
+def recommendation_id(resource_name: str) -> str:
+    """``customers/1/recommendations/abc`` -> ``abc``."""
+    return str(resource_name or "").rsplit("/", 1)[-1]
+
+
+def _clean_ids(values: list[str] | None, cid: str) -> tuple[list[str], list[str]]:
+    """Accept bare IDs or full resource names. Returns (errors, deduped IDs)."""
+    errors: list[str] = []
+    ids: list[str] = []
+    for raw in values or []:
+        value = str(raw or "").strip()
+        if not value:
+            continue
+        match = _RESOURCE_RE.match(value)
+        if match:
+            if match.group(1) != cid:
+                errors.append(
+                    f"{value} belongs to account {match.group(1)}, not {cid}"
+                )
+                continue
+            value = match.group(2)
+        elif not _ID_RE.match(value):
+            errors.append(f"'{value}' is not a recommendation ID or resource name")
+            continue
+        if value not in ids:
+            ids.append(value)
+    return errors, ids
+
+
+def _active_by_id(config: AdLoopConfig, customer_id: str) -> dict[str, dict]:
+    """Every active (not dismissed) recommendation, keyed by ID."""
+    from adloop.ads.read import get_recommendations
+
+    rows = get_recommendations(config, customer_id=customer_id).get(
+        "recommendations", []
+    )
+    return {
+        recommendation_id(row.get("recommendation.resource_name", "")): row
+        for row in rows
+        if row.get("recommendation.resource_name")
+    }
+
+
+def draft_dismiss_recommendations(
+    config: AdLoopConfig,
+    *,
+    customer_id: str = "",
+    recommendation_ids: list[str] | None = None,
+) -> dict:
+    """Draft dismissing recommendations — returns PREVIEW.
+
+    Reads the active recommendations first: an ID that is unknown or already
+    dismissed is refused by name, so the preview only ever lists what the
+    apply will turn down. Each entry carries its type, campaign and Google's
+    estimated improvement, the same numbers ``get_recommendations`` shows.
+
+    Call ``confirm_and_apply`` with the returned plan_id to execute.
+    """
+    from adloop.ads.client import normalize_customer_id
+    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)}
+
+    cid = normalize_customer_id(customer_id or config.ads.customer_id)
+    errors, ids = _clean_ids(recommendation_ids, cid)
+    if not ids and not errors:
+        errors.append("At least one recommendation_id is required")
+    if errors:
+        return {"error": "Validation failed", "details": errors}
+
+    active = _active_by_id(config, customer_id)
+    missing = [rec_id for rec_id in ids if rec_id not in active]
+    if missing:
+        return {
+            "error": "Validation failed",
+            "details": [
+                "Not an active recommendation in this account (unknown, or "
+                "already dismissed): " + ", ".join(missing)
+                + ". get_recommendations lists the active ones with their IDs."
+            ],
+        }
+
+    recommendations = [
+        {
+            "recommendation_id": rec_id,
+            "resource_name": active[rec_id]["recommendation.resource_name"],
+            "type": active[rec_id].get("recommendation.type", ""),
+            "campaign": active[rec_id].get("recommendation.campaign", ""),
+            "ad_group": active[rec_id].get("recommendation.ad_group", ""),
+            "estimated_improvement": active[rec_id].get("estimated_improvement", {}),
+        }
+        for rec_id in ids
+    ]
+    plan = ChangePlan(
+        operation=OPERATION,
+        entity_type="recommendation",
+        entity_id=",".join(ids),
+        customer_id=customer_id,
+        changes={
+            "recommendations": recommendations,
+            "count": len(recommendations),
+            "note": (
+                "Dismissing changes nothing in the account. Google can show a "
+                "dismissed recommendation again later."
+            ),
+        },
+    )
+    store_plan(plan)
+    return plan.to_preview()
+
+
+def preflight(config: AdLoopConfig, plan: object) -> dict:
+    """Dry run: every planned recommendation must still be active.
+
+    DismissRecommendation has no validate-only mode, so this re-read is the
+    whole check. Raises when any recommendation has gone (dismissed in the UI,
+    applied, or expired), so the dry run fails instead of reporting success.
+    """
+    planned = [r["recommendation_id"] for r in plan.changes["recommendations"]]
+    active = _active_by_id(config, plan.customer_id)
+    gone = [rec_id for rec_id in planned if rec_id not in active]
+    if gone:
+        raise ValueError(
+            "No longer active (dismissed, applied or expired since the "
+            "preview): " + ", ".join(gone) + ". Draft again."
+        )
+    return {"recommendations_checked": len(planned), "still_active": len(planned)}
+
+
+def _apply_dismiss_recommendations(client: object, cid: str, changes: dict) -> dict:
+    """Dismiss the planned recommendations; per-recommendation errors are reported."""
+    from adloop.ads.write import _parse_partial_failure_per_op
+
+    names = [r["resource_name"] for r in changes["recommendations"]]
+    service = client.get_service("RecommendationService")
+    request = client.get_type("DismissRecommendationRequest")
+    request.customer_id = cid
+    request.partial_failure = True
+    operation_type = type(request).DismissRecommendationOperation
+    for name in names:
+        request.operations.append(operation_type(resource_name=name))
+
+    response = service.dismiss_recommendation(request=request)
+
+    pf_error = getattr(response, "partial_failure_error", None)
+    per_op_errors = _parse_partial_failure_per_op(client, pf_error)
+    dismissed: list[str] = []
+    failed: list[dict] = []
+    for index, result in enumerate(response.results):
+        if result.resource_name:
+            dismissed.append(result.resource_name)
+        else:
+            failed.append(
+                {
+                    "recommendation_id": recommendation_id(names[index]),
+                    "error": per_op_errors.get(
+                        index, "Unknown error (see partial_failure_message)"
+                    ),
+                }
+            )
+
+    out: dict = {"dismissed": dismissed, "dismissed_count": len(dismissed)}
+    if failed:
+        out["partial_failure"] = True
+        out["failed"] = failed
+        message = getattr(pf_error, "message", "") if pf_error is not None else ""
+        if message:
+            out["partial_failure_message"] = message
+    return out

{adloop-0.35.1 → adloop-0.36.0}/src/adloop/ads/write.py

@@ -2717,6 +2717,9 @@ def confirm_and_apply(
     is_reddit = plan.operation.startswith("reddit_")
     is_gtm = plan.operation.startswith("gtm_")
     is_ga4 = plan.operation in GA4_OPERATIONS
+    # Google Ads calls without a validate_only field: the dry run re-reads the
+    # target instead, like the platforms above.
+    is_ads_reread = plan.operation == "dismiss_recommendations"
     platform_label = (
         "Reddit Ads" if is_reddit
         else "Google Tag Manager" if is_gtm
@@ -2749,6 +2752,12 @@ def confirm_and_apply(
                 from adloop.ga4.write import preflight as ga4_preflight
 
                 preflight_checks = ga4_preflight(config, plan)
+            elif is_ads_reread:
+                # DismissRecommendation has no validate_only field, and the
+                # validate-only client refuses it; re-read the targets instead.
+                from adloop.ads.recommendations import preflight as rec_preflight
+
+                preflight_checks = rec_preflight(config, plan)
             else:
                 # Google Ads checks the exact mutates with validate_only=True
                 # and executes nothing.
@@ -2784,7 +2793,7 @@ def confirm_and_apply(
             )
             checked_against = (
                 f"re-checked the target against {platform_label}"
-                if is_reddit or is_gtm or is_ga4
+                if is_reddit or is_gtm or is_ga4 or is_ads_reread
                 else "sent the change to Google Ads in validate-only mode"
             )
             return {
@@ -2835,7 +2844,9 @@ def confirm_and_apply(
         if preflight_checks is not None:
             response["checks"] = preflight_checks
             response["note"] = (
-                f"{platform_label} has no validate-only mode: the dry run "
+                f"{platform_label} has no validate-only mode"
+                + (" for dismissing recommendations" if is_ads_reread else "")
+                + ": the dry run "
                 "re-read the target and re-checked the safety gates; nothing "
                 "was changed live."
                 + (
@@ -4089,6 +4100,7 @@ def _dispatch_ads_plan(client: object, cid: str, plan: object) -> dict:
     from adloop.ads.pmax import apply_asset_group_assets as _apply_asset_group_assets
     from adloop.ads.pmax import apply_asset_group_signals as _apply_asset_group_signals
     from adloop.ads.pmax import apply_pmax_product_filter as _apply_pmax_product_filter
+    from adloop.ads.recommendations import _apply_dismiss_recommendations
     # Custom conversion goals live in their own module for the same reason.
     from adloop.ads.custom_conversion_goals import (
         _apply_assign_custom_conversion_goal,
@@ -4123,6 +4135,7 @@ def _dispatch_ads_plan(client: object, cid: str, plan: object) -> dict:
         "attach_brand_list_to_campaigns": _apply_attach_brand_list_to_campaigns,
         "detach_brand_list_from_campaigns": _apply_detach_brand_list_from_campaigns,
         "update_ai_max_settings": _apply_ai_max_settings,
+        "dismiss_recommendations": _apply_dismiss_recommendations,
         "create_custom_conversion_goal": _apply_create_custom_conversion_goal,
         "update_custom_conversion_goal": _apply_update_custom_conversion_goal,
         "assign_custom_conversion_goal": _apply_assign_custom_conversion_goal,

{adloop-0.35.1 → adloop-0.36.0}/src/adloop/cli.py

@@ -995,7 +995,7 @@ def _wizard_finish(
 
 def _maybe_offer_global_rules_install() -> None:
     """If Claude is detected, offer to install rules globally during init."""
-    from adloop.rules_install import detect_clients, install_rules
+    from adloop.rules_install import detect_clients, install_rules, rules_token_estimate
 
     clients = detect_clients()
     if not clients:
@@ -1017,16 +1017,19 @@ def _maybe_offer_global_rules_install() -> None:
         _print("  Skipping. Run `adloop install-rules` later if you change your mind.")
         return
 
+    # Lazy is the default: inline puts the full rules into every Claude Code
+    # session in every repository, AdLoop or not (#114).
+    tokens = rules_token_estimate() // 1000
     _print()
     _print("  Install mode:")
-    _print("    1. inline (default) — full rules in ~/.claude/CLAUDE.md")
-    _print("       Reliable; loaded every Claude Code session (~10K tokens).")
-    _print("    2. lazy — small directive in CLAUDE.md, full rules in")
-    _print("       ~/.claude/rules/adloop.md, loaded only when AdLoop is active.")
-    _print("       Cheaper baseline cost; slightly less reliable.")
+    _print("    1. lazy (default) — a short pointer in ~/.claude/CLAUDE.md; Claude")
+    _print("       reads the full rules (~/.adloop/rules/adloop.md) only when")
+    _print("       AdLoop tools are in use. Almost free in sessions without AdLoop.")
+    _print("    2. inline — the full rules in ~/.claude/CLAUDE.md, loaded into")
+    _print(f"       every Claude Code session (about {tokens}K tokens). Most reliable.")
     _print()
     raw = input("  Choose [1/2, default 1]: ").strip()
-    mode = "lazy" if raw == "2" else "inline"
+    mode = "inline" if raw == "2" else "lazy"
 
     _print()
     results = install_rules(mode=mode)

{adloop-0.35.1 → adloop-0.36.0}/src/adloop/rules/adloop.md

@@ -70,6 +70,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 | `get_brand_list_brands` | Contents of a brand list, with `entity_id` (the MID) and `criterion_id` (needed for removal) | `shared_set_id` (required) |
 | `get_brand_list_campaigns` | Which campaigns a brand list is attached to, and whether each attachment excludes (`role: excluded`) or targets (`role: targeted`) | `shared_set_id` (optional) |
 | `get_ai_max_settings` | The AI Max knobs of Search campaigns: `enable_ai_max`, `bundling_required`, the full `asset_automation_settings` list, and each ad group's `disable_search_term_matching` | `campaign_id` (optional) |
+| `get_campaign_settings` | Every setting that decides how far a Search campaign reaches, one flat record per campaign: networks, location option, campaign-level broad match, bidding and budget, tracking template / URL suffix / custom parameters, and the AI Max state. `widening_settings` and `insights[]` name anything that lets ads reach beyond the chosen keywords and locations. The one call for a recurring "did Google switch something on?" audit | `campaign_id` (optional) |
 | `get_custom_conversion_goals` | Custom conversion goals (named sets of conversion actions) and one campaign's goal config | `campaign_id` (optional) |
 | `run_gaql` | Custom queries not covered by other tools | `query`, `format` (table/json/csv) |
 
@@ -79,7 +80,7 @@ You have access to AdLoop MCP tools that connect Google Ads, Reddit Ads and Goog
 - `get_ad_performance` returns full `headlines` and `descriptions` lists for RSAs, plus `ad_group_ad.policy_summary.approval_status`, `review_status` and `policy_topics` (topic names only) per ad. Ads that are `DISAPPROVED` (cannot serve) or `APPROVED_LIMITED` (serving restricted) are listed in `policy_issues` with their spend and flagged in `insights[]`; compact mode adds `by_approval_status` counts.
 - `get_campaign_performance` returns `metrics.search_impression_share`, `metrics.search_budget_lost_impression_share` and `metrics.search_rank_lost_impression_share` as fractions (0.25 = 25%) with matching `*_pct` percentages. Google caps the reported values: 0.0999 means below 10% share, 0.9001 means above 90% lost. They are `null` for campaigns that do not serve on Search (Display, Video, PMax, ...) or had no impressions, which means "does not apply", not zero. `budget_limited_converters` and `insights[]` flag converting campaigns losing 20% or more of impressions to budget: those can absorb more budget, rank-lost share instead points at bids, ad relevance and quality.
 - `get_change_history` returns changes newest first with counts `by_resource_type`, `by_client`, `by_user` and `by_day`. Google Ads keeps 30 days of change history, so an older start date is moved forward (see `notes`). `insights[]` flag auto-applied recommendations and budget or bidding changes. `truncated: true` means the limit was hit; narrow the range or filters to see older changes.
-- `get_recommendations` returns `estimated_improvement` per recommendation (potential minus base metrics) and `insights[]` that flag budget-increase recommendations, whose projected gain comes from spending more.
+- `get_recommendations` returns each recommendation's `recommendation.id` (what `draft_dismiss_recommendations` takes) and `estimated_improvement` per recommendation (potential minus base metrics) and `insights[]` that flag budget-increase recommendations, whose projected gain comes from spending more.
 - PMax tools: `get_pmax_performance` returns `insights[]` flagging weak ad strength and zero-conversion asset groups. `segments.ad_network_type` includes MIXED — a Google catch-all for most PMax traffic. Full channel splits (Search vs YouTube vs Display vs Discover) are not available via the API.
 - `get_pmax_assets` returns `by_status` and `by_field_type` summaries. Note: per-asset performance labels (BEST/GOOD/LOW) are not available for PMax assets in the Google Ads API. Use `get_detailed_asset_performance` for quality signals via top combinations.
 - `get_audience_performance` works for campaigns with explicit audience targeting. PMax audience targeting is automatic and may not appear in this report. When the results include SEARCH campaigns, `insights[]` reminds you that custom segments cannot be attached to them (see the compatibility matrix below) — relay that constraint instead of proposing impossible pairings.
@@ -317,6 +318,7 @@ Conversions that happen offline (a sales call, a lead that turned into a deal) g
 | `add_to_negative_keyword_list` | Append keywords to an EXISTING shared negative keyword list (does NOT add) | `shared_set_id` (from `get_negative_keyword_lists`), keyword list, `match_type` |
 | `attach_shared_set_to_campaigns` | Attach an EXISTING shared set (e.g. shared negative keyword list) to one or more campaigns. Use after creating a campaign to inherit pre-built negatives. | `shared_set_id` (from `get_negative_keyword_lists`), `campaign_ids` list |
 | `detach_shared_set_from_campaigns` | Detach a shared set from one or more campaigns. Removes only the linkage; the shared set and its keywords stay intact. | `shared_set_id`, `campaign_ids` list |
+| `draft_dismiss_recommendations` | Dismiss Google recommendations the user has decided not to take. Nothing in the account changes and Google can show them again later; unknown or already dismissed IDs are refused. No validate-only mode: the dry run re-reads the account and checks each one is still active | `recommendation_ids` (`recommendation.id` from `get_recommendations`) |
 | `draft_demographic_targeting` | Propose demographic criteria (age, gender, parental status, income range) at ad group or campaign level. Defaults to EXCLUSION (`negative=True`). | exactly one of `ad_group_id` or `campaign_id`, at least one of `age_ranges`/`genders`/`parental_statuses`/`income_ranges`, optional `negative` (default True) |
 | `draft_audience_attachment` | Attach audiences to a campaign or ad group as OBSERVATION (default: bids and reporting, reach unchanged), TARGETING (ads only reach the audiences; double confirmation) or exclusion. Refuses incompatible pairings, Search lists too small to target, audiences at both campaign and ad group level, and Performance Max | exactly one of `campaign_id` or `ad_group_id`; any of `user_list_ids`, `segment_ids`, `custom_audience_ids`, `combined_audience_ids`; `mode` observation/targeting; `exclude` |
 | `draft_ai_max_settings` | Draft AI Max controls for one Search campaign: `enable_ai_max`, per-ad-group `disable_search_term_matching`, text and final-URL asset automation. Refuses a plan that would switch AI Max on while an automation it was never told about keeps running; an explicitly requested automation asks for a double confirmation. | `campaign_id`, optional `enable_ai_max`, optional `disable_search_term_matching`, optional `ad_group_ids`, optional `include_paused_ad_groups`, optional `text_asset_automation`, optional `final_url_expansion` |
@@ -657,6 +659,7 @@ Reddit's structure is campaign → ad group (budget, bid, pixel, targeting) →
 4. Use `estimated_improvement` to prioritize: recommendations with >1 estimated additional conversion are worth investigating
 5. For keyword recommendations, call `get_keyword_performance` to check existing keyword overlap before acting
 6. Present recommendations grouped by type with your assessment of each — the user should understand which ones are genuinely helpful vs which ones just increase Google's revenue
+7. For the ones the user decides not to take, offer `draft_dismiss_recommendations` with their IDs, so they stop reappearing. Dismiss only what the user turned down: a dismissal is not a verdict you make on their behalf
 
 ### When user asks about audience performance or targeting
 

{adloop-0.35.1 → adloop-0.36.0}/src/adloop/rules_install.py

@@ -20,12 +20,14 @@ on upgrade. Anything outside the sentinel pair is preserved verbatim.
 Two install modes:
 
 - **inline** (default): the full rules text is pasted between the sentinels
-  in ``~/.claude/CLAUDE.md``. Reliable but ~10K tokens loaded every Claude
-  Code session.
+  in ``~/.claude/CLAUDE.md``. Reliable, but loaded into every Claude Code
+  session in every repository (:func:`rules_token_estimate`, about 30K tokens).
 - **lazy**: a small directive is written between the sentinels pointing at
-  ``~/.claude/rules/adloop.md`` (which contains the full rules). The LLM is
+  ``~/.adloop/rules/adloop.md`` (which contains the full rules). The LLM is
   instructed to read the rules file only when AdLoop tools are in scope.
-  Cheaper baseline cost, less reliable.
+  The file deliberately lives outside ``~/.claude/``: Claude Code loads every
+  file in ``~/.claude/rules/`` into every session, which is where lazy mode
+  used to write it (#114). Cheaper baseline cost, less reliable.
 
 Slash commands are installed namespaced (``adloop-*``) so they don't collide
 with user-defined commands of the same name.
@@ -61,11 +63,18 @@ _SENTINEL_BLOCK_RE = re.compile(
 
 InstallMode = Literal["inline", "lazy"]
 
+# Where lazy mode keeps the full rules, relative to the home directory. Not
+# under ~/.claude/: Claude Code auto-loads everything in ~/.claude/rules/.
+LAZY_RULES_RELATIVE = Path(".adloop") / "rules" / "adloop.md"
+# Where lazy mode wrote them before #114. Cleaned up when it is ours.
+_LEGACY_LAZY_RULES_RELATIVE = Path(".claude") / "rules" / "adloop.md"
+_RULES_HEADING = "# AdLoop — AI Orchestration Rules"
+
 # The directive used in lazy mode. Kept short to minimise baseline token cost.
 _LAZY_DIRECTIVE = """\
 **AdLoop orchestration**: if MCP tools like `get_campaign_performance`,
 `run_gaql`, `draft_responsive_search_ad`, or other AdLoop tools are available
-in this session, read `~/.claude/rules/adloop.md` for the full safety rules,
+in this session, read `~/.adloop/rules/adloop.md` for the full safety rules,
 orchestration patterns, and GAQL reference before using them. Skip this read
 if AdLoop is not active in the current session.
 """
@@ -182,7 +191,7 @@ def _read_bundled_rules() -> str:
     """Load the bundled rules markdown shipped with the package.
 
     Returns the file as-is (with its YAML frontmatter intact) since lazy mode
-    writes it to ``~/.claude/rules/adloop.md`` where the frontmatter is
+    writes it to ``~/.adloop/rules/adloop.md`` where the frontmatter is
     meaningful. For inline mode, use :func:`_read_bundled_rules_body`.
     """
     ref = importlib.resources.files("adloop.rules").joinpath("adloop.md")
@@ -203,6 +212,38 @@ def _read_bundled_rules_body() -> str:
     return text[end + 3:].lstrip("\n")
 
 
+def rules_token_estimate() -> int:
+    """Rough token cost of the inline rules, measured from the bundled file.
+
+    About four bytes per token, rounded to the nearest thousand, so the
+    wizard and README never quote a stale hard-coded figure again.
+    """
+    size = len(_read_bundled_rules_body().encode("utf-8"))
+    return max(1000, round(size / 4 / 1000) * 1000)
+
+
+def _home_of(rules_target: Path) -> Path:
+    """``~/.claude/CLAUDE.md`` -> ``~``."""
+    return rules_target.parent.parent
+
+
+def _remove_if_ours(path: Path) -> None:
+    """Delete a rules file AdLoop wrote; never a file the user wrote."""
+    if not path.is_file():
+        return
+    try:
+        text = path.read_text()
+    except (OSError, UnicodeDecodeError):
+        return
+    if _RULES_HEADING not in text:
+        return
+    path.unlink()
+    try:
+        path.parent.rmdir()  # only if empty
+    except OSError:
+        pass
+
+
 def _list_bundled_commands() -> list[tuple[str, str]]:
     """Return ``[(filename, content), ...]`` for every bundled slash command."""
     commands: list[tuple[str, str]] = []
@@ -335,16 +376,10 @@ def uninstall_rules(
                     client.rules_target.write_text(cleaned)
                 result.action = "uninstalled"
 
-        # Remove the lazy-mode rules file if present
-        lazy_rules_file = (
-            client.rules_target.parent / "rules" / "adloop.md"
-        )
-        if lazy_rules_file.exists():
-            lazy_rules_file.unlink()
-            try:
-                lazy_rules_file.parent.rmdir()  # only if empty
-            except OSError:
-                pass
+        # Remove the lazy-mode rules file, at its current and its old place.
+        home = _home_of(client.rules_target)
+        _remove_if_ours(home / LAZY_RULES_RELATIVE)
+        _remove_if_ours(home / _LEGACY_LAZY_RULES_RELATIVE)
 
         # Remove namespaced slash commands
         if remove_commands and client.commands_dir and client.commands_dir.exists():
@@ -397,11 +432,18 @@ def _apply_to_clients(
         else:
             resolved_mode = "inline"
 
-        # In lazy mode, the full rules go to a sibling file.
+        # In lazy mode the full rules go to a file Claude Code does not load
+        # on its own. A file from an older lazy install under ~/.claude/rules/
+        # would be loaded into every session, so it goes either way; inline
+        # mode needs no lazy file at all.
+        home = _home_of(rules_target)
+        _remove_if_ours(home / _LEGACY_LAZY_RULES_RELATIVE)
+        lazy_rules_file = home / LAZY_RULES_RELATIVE
         if resolved_mode == "lazy":
-            lazy_rules_dir = rules_target.parent / "rules"
-            lazy_rules_dir.mkdir(parents=True, exist_ok=True)
-            (lazy_rules_dir / "adloop.md").write_text(_read_bundled_rules())
+            lazy_rules_file.parent.mkdir(parents=True, exist_ok=True)
+            lazy_rules_file.write_text(_read_bundled_rules())
+        else:
+            _remove_if_ours(lazy_rules_file)
 
         new_block = _build_managed_block(resolved_mode, rules_target)
         merged = _replace_or_append_block(existing, new_block)
@@ -431,8 +473,10 @@ def _existing_block_is_lazy(existing: str) -> bool:
     if not match:
         return False
     block = match.group(0)
-    # Lazy blocks are short and reference the rules file path.
-    return "~/.claude/rules/adloop.md" in block and len(block) < 2000
+    # Lazy blocks are short and reference the rules file path (the current one,
+    # or the ~/.claude/rules/ one older versions wrote).
+    mentions_file = "~/.adloop/rules/adloop.md" in block or "~/.claude/rules/adloop.md" in block
+    return mentions_file and len(block) < 2000
 
 
 # ---------------------------------------------------------------------------

{adloop-0.35.1 → adloop-0.36.0}/src/adloop/server.py

@@ -1546,10 +1546,12 @@ def get_recommendations(
 ) -> dict:
     """Retrieve Google's auto-generated recommendations with estimated impact.
 
-    Returns each recommendation's type, associated campaign/ad group, current
-    (base) and projected (potential) metrics, and the estimated improvement.
-    Includes insights that flag budget-increase recommendations (their projected
-    gain comes from spending more) and highlight high-impact suggestions.
+    Returns each recommendation's ID, type, associated campaign/ad group,
+    current (base) and projected (potential) metrics, and the estimated
+    improvement. Includes insights that flag budget-increase recommendations
+    (their projected gain comes from spending more) and highlight high-impact
+    suggestions. The `recommendation.id` is what draft_dismiss_recommendations
+    takes.
 
     Args:
         customer_id: Google Ads customer ID, digits with or without dashes
@@ -1570,6 +1572,44 @@ def get_recommendations(
     )
 
 
+@_tool(title="Draft dismissing recommendations", annotations=_WRITE, tags={"ads"})
+@_safe
+def draft_dismiss_recommendations(
+    recommendation_ids: _StrList,
+    customer_id: str = "",
+) -> dict:
+    """Dismiss Google Ads recommendations — returns a PREVIEW.
+
+    Turns down recommendations you will not take (e.g. "add broad match" on a
+    deliberately narrow account) so they stop reappearing in
+    get_recommendations. Nothing in the account changes, and Google can show a
+    dismissed recommendation again later, so a single confirmation is enough.
+
+    Each ID must be an active recommendation: unknown or already dismissed
+    IDs are refused by name. The preview lists each one's type, campaign and
+    estimated improvement, so the user sees what they are turning down.
+
+    DismissRecommendation has no validate-only mode: the dry run re-reads the
+    account and checks every recommendation is still active instead of
+    sending the call to Google. The returned plan_id is applied with
+    confirm_and_apply.
+
+    Args:
+        recommendation_ids: `recommendation.id` values from
+            get_recommendations, or full resource names
+            (customers/{customer_id}/recommendations/{id}). Duplicates are
+            collapsed.
+        customer_id: Ads account ID. Defaults to the configured account.
+    """
+    from adloop.ads.recommendations import draft_dismiss_recommendations as _impl
+
+    return _impl(
+        current_config(),
+        customer_id=customer_id or current_config().ads.customer_id,
+        recommendation_ids=recommendation_ids,
+    )
+
+
 @_tool(title="Performance Max performance", annotations=_READONLY, tags={"ads"})
 @_safe
 def get_pmax_performance(
@@ -3980,6 +4020,44 @@ def get_ai_max_settings(
         campaign_id=campaign_id,
     )
 
+
+@_tool(title="Campaign settings", annotations=_READONLY, tags={"ads"})
+@_safe
+def get_campaign_settings(
+    campaign_id: str = "",
+    customer_id: str = "",
+) -> dict:
+    """Read every setting that decides how far a Search campaign reaches, in one call.
+
+    Returns one flat record per campaign: status, bidding strategy and its
+    target or CPC ceiling, daily budget and whether it is shared, the Google
+    Search / search partner / Display network flags, the location option
+    (positive_geo_target_type) and its negative counterpart, campaign-level
+    broad match (keyword_match_type), the tracking template, final URL suffix
+    and custom parameters, and the AI Max state get_ai_max_settings reports
+    (enable_ai_max, asset automation per type). Money is in the account
+    currency (`currency`).
+
+    Each campaign lists its `widening_settings`: search partners or Display on,
+    a presence-or-interest location option, broad match on, AI Max on, an
+    automation opted in. `insights[]` names the campaigns that have any. Made
+    for recurring audits: the same call every week diffs cleanly.
+
+    Args:
+        campaign_id: Numeric campaign ID of a Search campaign. When omitted,
+            every non-removed Search campaign in the account is listed.
+        customer_id: Google Ads customer ID (digits, dashes optional). Defaults to
+            the configured account.
+    """
+    from adloop.ads.campaign_settings import get_campaign_settings as _impl
+
+    return _impl(
+        current_config(),
+        customer_id=customer_id or current_config().ads.customer_id,
+        campaign_id=campaign_id,
+    )
+
+
 @_tool(title="Draft AI Max settings", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_ai_max_settings(