# v3.2 Opt-Ins: Re-enabling Removed Hooks and Ambient Insight Capture

**Version 3.2.0** | A guide to the opt-in mechanisms that compensate for the global hooks removed in v3.1

In v3.0 and earlier, four global hooks fired automatically on every Claude Code operation in every project:

- `SessionStart` — printed a brand summary banner + ran dependency check
- `PreToolUse Write|Edit` — ran a brand compliance + hallucination check on every file edit
- `PreToolUse mcp_.*` — gated every MCP tool call from every plugin through a brand compliance prompt (the most invasive)
- `SessionEnd` — auto-prompted insight saving on every session end

v3.1 removed all four because Claude Code plugin hooks have no per-directory or per-project scoping — they fire globally regardless of context. Removing them was the right call for multi-plugin coexistence (especially the `mcp_.*` matcher, which intercepted every MCP write from every installed plugin).

But the work those hooks did was useful. v3.2 reintroduces every capability as an explicit opt-in, with stronger architectural guarantees than the global hooks ever had.

This guide explains every v3.2 opt-in and how to enable each.

---

## Table of Contents

1. [What Was Lost vs What Now Compensates](#1-what-was-lost-vs-what-now-compensates)
2. [Opt-In: Re-enable Hooks at Your Own Settings Level](#2-opt-in-re-enable-hooks-at-your-own-settings-level)
3. [Opt-In: Ambient Insight Capture (`auto_save_insights`)](#3-opt-in-ambient-insight-capture-auto_save_insights)
4. [On-Demand Replacements: `/digital-marketing-pro:status` and `/digital-marketing-pro:check`](#4-on-demand-replacements-dmstatus-and-dmcheck)
5. [Embedded Safety: Hallucination Check Inside Content-Producer Agents](#5-embedded-safety-hallucination-check-inside-content-producer-agents)
6. [Recommended Workflow](#6-recommended-workflow)

---

## 1. What Was Lost vs What Now Compensates

| Hook removed | What was lost | v3.2 compensation | Severity of original loss |
|---|---|---|---|
| `SessionStart` (brand banner) | Auto-visibility of active brand at session start | `/digital-marketing-pro:status` (on-demand, richer) | Low — convenience |
| `PreToolUse Write|Edit` (compliance + hallucination check) | Real-time hallucination detection on every file write | (a) Embedded in 4 content-producer agents; (b) `/digital-marketing-pro:check` on demand; (c) opt-in re-enable per project | **High** — real safety net |
| `PreToolUse mcp_.*` (MCP write gate) | Brand-compliance gate on every MCP write across all plugins | Per-agent decision flows for marketing-side MCP writes | Negligible loss; major net win |
| `SessionEnd` (insight saving) | Auto-capture of session learnings | `auto-save-insight.py` opt-in helper + `auto_save_insights: true` brand flag | Medium |

---

## 2. Opt-In: Re-enable Hooks at Your Own Settings Level

The original hook configurations are preserved at `hooks/hooks-reference.example.json` as a documented reference. You can re-enable any of them in your own user-level or project-level settings — without affecting other users of the plugin.

### Why this is the right pattern

When a plugin ships a hook, that hook fires globally for every user who installs the plugin. There is no way to scope it to specific projects or to make it opt-in per user. This forces the plugin author to choose between:

- Ship the hook → all users get it across all their work, even unrelated projects (the v3.0 problem)
- Don't ship the hook → users who want it have to add it themselves

v3.1 chose the latter. v3.2 documents how to add it back **at your own settings level** if you want it.

### Re-enable a hook in your user-level settings

Your user-level settings live at `~/.claude/settings.json` (Linux/macOS) or `%USERPROFILE%\.claude\settings.json` (Windows). Hooks added here fire for all your Claude Code sessions but only for you, not for other plugin users.

Example: re-enable the `SessionStart` brand summary banner

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "timeout 30 python3 ~/path/to/digital-marketing-pro/scripts/setup.py --check-deps --summary"
          }
        ]
      }
    ]
  }
}
```

(Adjust the path to point to your local DMP installation.)

### Re-enable a hook in project-level settings

Project-level settings live at `.claude/settings.json` (committed to the project) or `.claude/settings.local.json` (gitignored, personal). Hooks added here fire only when you are working in that project directory.

This is the **safest place** to re-enable hooks because they only fire when relevant — exactly the per-directory scoping that plugin-shipped hooks lack.

Example: project-level settings.local.json that re-enables the `Write|Edit` compliance check only for this project

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "{copy the prompt verbatim from hooks/hooks-reference.example.json under SessionStart -> PreToolUse Write|Edit -> hooks[0].prompt}"
          }
        ]
      }
    ]
  }
}
```

### Recommended: do NOT re-enable the `mcp_.*` matcher

The `PreToolUse mcp_.*` matcher in the reference file is documented as "the worst offender" because it intercepts every MCP tool call from every plugin (Slack, Notion, GitHub MCP, Stripe, etc.) and forces a brand-compliance prompt regardless of context.

If you re-enable this hook, even at project-level, it will fire on every MCP write from every plugin you have configured. This is rarely what you want.

The recommended approach for MCP write safety is:

- For marketing-side writes: use the marketing agents (`publish-blog`, `send-email-campaign`, `launch-ad-campaign`, etc.) which have approval logic in their skill prompts
- For non-marketing writes: trust the source plugin's safety mechanisms; do not add a cross-plugin gate

### Re-enable the `SessionEnd` insight prompt

If you want the v3.0 SessionEnd insight-saving prompt back at the user or project level, copy the `SessionEnd` block from `hooks/hooks-reference.example.json` into your settings. But also consider the cleaner v3.2 alternative: **enable `auto_save_insights: true` in your brand profile**, which lets agents save insights as they go without needing a session-end prompt at all.

---

## 3. Opt-In: Ambient Insight Capture (`auto_save_insights`)

### What it does

When the brand profile contains `"auto_save_insights": true`, marketing agents (content-creator, email-specialist, social-media-manager, pr-outreach, the engagement workflow) can call `scripts/auto-save-insight.py` at meaningful checkpoints to save session learnings. Without the flag, those calls are clean no-ops.

### How to enable

Add the flag to your brand's `profile.json`:

```json
{
  "brand_name": "Acme Corp",
  "brand_slug": "acme-corp",
  "auto_save_insights": true,
  "...": "...rest of the profile..."
}
```

Or programmatically:

```bash
python -c "
import json, pathlib
p = pathlib.Path.home() / '.claude-marketing/brands/acme-corp/profile.json'
d = json.loads(p.read_text())
d['auto_save_insights'] = True
p.write_text(json.dumps(d, indent=2))
print('opted in')
"
```

### How agents use it

Agents that produce content or run analyses should call the helper at meaningful end-of-task checkpoints:

```bash
python "${CLAUDE_PLUGIN_ROOT}/scripts/auto-save-insight.py" \
    --brand acme-corp \
    --type session_learning \
    --insight "LinkedIn Document Ads outperformed Sponsored Content for our B2B audience" \
    --context "Q2 2026 social campaign post-mortem" \
    --source "social-media-manager + analytics-analyst"
```

The script:

1. Reads `~/.claude-marketing/brands/acme-corp/profile.json`
2. Checks for `"auto_save_insights": true`
3. If present and `true` → saves the insight via `campaign-tracker.py` (or direct write fallback) into `brands/{slug}/insights.json`
4. If absent or `false` → returns `{"status": "no_op", "reason": "auto_save_insights not enabled"}` — no error, no surprise side effect

### Why this is better than the SessionEnd hook

- **Fires only on meaningful events**, not at every session end
- **Each insight is contextual** — the calling agent provides the context and source
- **User opts in per brand**, not globally
- **No cross-project noise** — only fires when an actual marketing skill is running
- **Inspectable in `/digital-marketing-pro:status`** — the brand snapshot shows whether opt-in is enabled

### Insight types

Recommended `--type` values for consistency:

| Type | When to use |
|---|---|
| `session_learning` | Any meaningful learning from a session (default) |
| `campaign_outcome` | Post-campaign performance learnings |
| `audience_finding` | Insights about audience behaviour, response patterns, segmentation |
| `competitive` | Competitor activity, positioning shifts, white-space discoveries |
| `voice_drift` | Brand voice consistency observations |
| `compliance_observation` | Patterns about what compliance constraints affect the strategy |
| `channel_pattern` | Channel-level performance patterns or surprises |

### Inspection

See your captured insights any time:

```bash
/digital-marketing-pro:status --section insights
```

Or directly:

```bash
python scripts/dm-status.py --section insights --brand acme-corp
```

---

## 4. On-Demand Replacements: `/digital-marketing-pro:status` and `/digital-marketing-pro:check`

These two commands replace the on-demand value of the removed `SessionStart` and `PreToolUse Write|Edit` hooks.

### `/digital-marketing-pro:status`

Replaces the SessionStart brand banner with a richer on-demand snapshot.

```
/digital-marketing-pro:status                              # Full snapshot for active brand
/digital-marketing-pro:status --quiet                      # One-line: DMP STATUS | Acme Corp | engagements: 2 | deps: full
/digital-marketing-pro:status --json                       # JSON for downstream skills
/digital-marketing-pro:status --brand acme-corp            # Specific brand
/digital-marketing-pro:status --section engagements        # Single section
```

Shows: brand profile, engagement state per engagement, recent insights, recent compliance violations, Python dependency mode.

See: [skills/status/SKILL.md](../skills/status/SKILL.md), [scripts/dm-status.py](../scripts/dm-status.py).

### `/digital-marketing-pro:check`

Replaces the PreToolUse compliance + hallucination check with an explicit pre-publish gate.

```
/digital-marketing-pro:check drafts/q2-blog.md                         # Quick eval (~2s, no deps)
/digital-marketing-pro:check drafts/q2-blog.md --full --brand acme    # Full multi-dimension eval
/digital-marketing-pro:check drafts/health-ad.md --compliance --brand healthfirst --evidence facts.json --schema ad_copy
```

Wraps `scripts/eval-runner.py` and produces a single PASS / WARN / BLOCKED decision with actionable issues.

See: [skills/check/SKILL.md](../skills/check/SKILL.md), [commands/check.md](../commands/check.md).

---

## 5. Embedded Safety: Hallucination Check Inside Content-Producer Agents

The biggest gap from removing the `PreToolUse Write|Edit` hook was loss of automatic hallucination detection on every marketing content write. v3.2 closes this gap by **embedding the hallucination check directly inside the four most-used content-producer agents**:

- `agents/content-creator.md` — Behaviour Rule 12
- `agents/email-specialist.md` — Behaviour Rule 11
- `agents/social-media-manager.md` — Behaviour Rule 11
- `agents/pr-outreach.md` — Behaviour Rule 10

Each rule mandates that the agent run `hallucination-detector.py` on its final draft before returning content to the user. The check rules are:

- **CRITICAL findings** → DO NOT deliver. Return issues + suggested fixes; ask user for input or revise.
- **WARNING findings** → Deliver but include warnings inline so the user can address before publishing.
- Always report the check status in the output.

This is **stronger than the v3.0 hook** for three reasons:

1. The check runs on the actual draft the agent intends to deliver, not on every Write/Edit operation (some of which are intermediate working files that should not be checked)
2. The agent has the context to interpret findings appropriately (a "WARNING" stat in a draft might be intentional pending evidence)
3. The check is an integral part of the agent's deliverable contract, not an external gate

For agents that are **not yet updated** (most v2.x agents do not have the rule), users should run `/digital-marketing-pro:check` manually before publishing.

To extend the embedded check to other agents, follow the pattern in `agents/content-creator.md` Behaviour Rule 12. See [CONTRIBUTING.md](../CONTRIBUTING.md) Section "Skills that participate in the v3.0 engagement methodology" for related conventions.

---

## 6. Recommended Workflow

### Minimum (no opt-ins)

If you do not enable any opt-ins, the v3.2 plugin still works. Workflow becomes:

- At session start: type `/digital-marketing-pro:status` if you want to confirm active brand
- During work: agents that have embedded hallucination check (content-creator, email-specialist, social-media-manager, pr-outreach) auto-check their output
- Before publishing any content: run `/digital-marketing-pro:check <file> --full --brand <slug>`
- For compliance-critical content: run `/digital-marketing-pro:check <file> --compliance --brand <slug> --evidence <facts.json>`
- Insight capture: only when you explicitly call `auto-save-insight.py --force` or use the engagement Part 12 loop

### Recommended (opt in to ambient capture)

For brands you actively work on with engagement workflows:

1. Enable `auto_save_insights: true` in the brand profile
2. Periodically run `/digital-marketing-pro:status --section insights` to review what is being captured
3. At quarter end, run `/digital-marketing-pro:engagement loop <brand> <id>` to produce the Part 12 quarterly improvement brief

### Power-user (re-enable hooks at user level)

If you want the v3.0 ambient experience back for your personal sessions only:

1. Copy the `SessionStart` and `SessionEnd` blocks from `hooks/hooks-reference.example.json` into `~/.claude/settings.json`
2. Adjust the `command` paths to point to your local DMP installation
3. Do NOT re-enable the `PreToolUse mcp_.*` matcher — it will affect every MCP plugin you use

### Project-scoped (re-enable hooks per project)

For specific projects where you want the v3.0 ambient experience:

1. Copy the same blocks into `.claude/settings.local.json` in the project directory
2. The hooks now fire only when working in that project, not globally

This is the cleanest way to get the v3.0 behaviour back for marketing-specific projects without affecting your other work.

---

## Related References

- [hooks/hooks-reference.example.json](../hooks/hooks-reference.example.json) — preserved v3.0 hook configurations with rationale notes
- [scripts/auto-save-insight.py](../scripts/auto-save-insight.py) — opt-in insight capture helper
- [scripts/dm-status.py](../scripts/dm-status.py) — `/digital-marketing-pro:status` underlying script
- [scripts/eval-runner.py](../scripts/eval-runner.py) — `/digital-marketing-pro:check` underlying orchestrator
- [skills/check/SKILL.md](../skills/check/SKILL.md) — `/digital-marketing-pro:check` skill
- [skills/status/SKILL.md](../skills/status/SKILL.md) — `/digital-marketing-pro:status` skill
- [commands/check.md](../commands/check.md) — `/digital-marketing-pro:check` command
- [commands/status.md](../commands/status.md) — `/digital-marketing-pro:status` command
- [docs/getting-started.md](getting-started.md) — main onboarding
- [CHANGELOG.md](../CHANGELOG.md) — v3.1 hook removal + v3.2 compensation history
