Spec 27: active-surfacing meta-agent — proactive nudges via the hooks surface

[0bserver07]

Goal

Make the meta-agent speak up proactively — before the user makes a mistake the store has already seen them make. "You tried this 2 weeks ago and it broke X" right when the agent is about to repeat it, not 3 days later.

Why now

Meta-agent (v0.8.0) is a Q&A sidebar today — the user has to ask. Hooks (v0.7.0) capture every tool-call, prompt, and stop event. Wiring them together turns the meta-agent from passive to active.

Schema

None. Reuses captured_events (v010) + the meta-agent tool catalogue. Surfaces appear in the existing meta-agent UI as "proactive" messages.

User-visible surface

• Hook: when stackunderflow hooks install is run with --proactive (new flag), it adds a UserPromptSubmit hook that POSTs the prompt + project + recent-touched-files to POST /api/meta-agent/proactive and waits for an optional response.
• API: POST /api/meta-agent/proactive — takes {prompt, project, recent_files}, runs the meta-agent's tool catalogue against it (file-risk, search-past-decisions, find-failure-modes-for-file), returns {should_surface: bool, message: str, evidence: [...]}.
• UI: the meta-agent sidebar surfaces a "💡 Heads-up" message above the user's next assistant turn when should_surface=true.
• Settings: STACKUNDERFLOW_PROACTIVE_ENABLED (default off — opt-in).

Implementation plan

1. Extend stackunderflow hooks install with --proactive.
2. New route routes/meta_agent.py:proactive_handler.
3. New service services/meta_agent_proactive.py:
   • should_speak_up(conn, prompt, project, recent_files) -> dict — runs a fixed set of read-only tools, returns a dict the LLM can summarise.
   • LLM call to summarise (with strict short-output prompt — max 2 sentences).
   • "Should surface" gate — only surface when one of:
     • File-risk count >= 3 reverts in 30d
     • Search-past-decisions hits a session marked outcome=failed or reverted
     • The current prompt is highly similar (cosine, via Spec 10 embeddings if available) to a past outcome=failed session
4. Frontend: extend MetaAgentSidebar to render proactive messages distinctly (different bubble color, dismissable).

Tests

• Synthetic store: file with 3 reverts → POST proactive → assert should_surface=true + message mentions the file.
• File with 0 reverts → assert should_surface=false.
• Hook command writes to captured_events (existing pattern).
• LLM summary respects the 2-sentence cap.

Hard parts

• Latency. The hook fires on every user prompt — if the proactive call takes >500ms, the user feels it. Cap at 500ms total; return should_surface=false on timeout.
• Annoyance threshold. Surface too often → user disables. Tune the gate aggressively: only surface high-confidence, high-impact warnings. Add a per-session "snooze" so the same warning doesn't fire 5 times.
• Privacy: proactive sends the user's prompt to the LLM. Document this clearly. Default off.

Out of scope

• Auto-applying remediation (just a nudge).
• Per-team proactive rules (defer to multi-device sync — Spec 28).

Dependencies

• Meta-agent (v0.8.0) shipped.
• Hooks (v0.7.0) shipped.
• Better signal with Spec 16 (file-risk) + Spec 22 (outcome attribution v2) — but works with existing data.

Estimated effort

Size L — single agent, ~2 hr.

Hard rules

• DO NOT touch versions / CHANGELOG headings.
• No schema migration.
• Branch: feat/proactive-meta-agent off main.
• Default OFF — must be opt-in via flag.