Research-Stack/6-Documentation/docs/specs/break_glass_mcp_agent.md

break-glass MCP Agent — Design Spec

Purpose: A last-resort agent that assembles a focused multi-model panel to attack novel issues that have resisted all other approaches.

Cost model: Each invocation costs 3-5× a single model call. The gate ensures it's only triggered when the alternative is human time (more expensive).

---

Trigger Protocol

The agent MUST NOT be called automatically. It requires an explicit trigger:

break glass: <problem statement>

Before invoking, the caller MUST have already tried:

1. The local model (Hermes3 / current default)
2. A single frontier model (Claude Opus / GPT-5.5)
3. The existing skill/tool system

Only when all three fail on the SAME problem should the trigger fire.

---

Architecture

┌─────────────────┐
│  Caller (agent   │
│  or human)       │
│                  │
│  "break glass:   │
│   cleanMerge_    │
│   preservesGap   │
│   sorry"         │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────────────┐
│  DIAGNOSE       │     │  Context Assembly     │
│                 │────▶│                       │
│  - Parse problem│     │  - Read relevant files│
│  - Classify type│     │  - Extract sorry/     │
│  - Estimate     │     │    error context      │
│    complexity   │     │  - Pull AGENTS.md     │
│                 │     │    constraints        │
└────────┬────────┘     │  - Gather build logs  │
         │              └──────────┬───────────┘
         │                         │
         ▼                         ▼
┌─────────────────────────────────────────────┐
│            PANEL SELECTION                   │
│                                              │
│  Problem type → Model panel:                 │
│                                              │
│  lean_proof    → [Claude Opus, DeepSeek V4,  │
│                   Gemini 3.1 Pro]            │
│  code_bug      → [GPT-5.5, Claude Fable,    │
│                   Kimi K2.6]                 │
│  architecture  → [Claude Opus, GPT-5.5,     │
│                   Gemini 3.1 Pro]            │
│  math_novel    → [DeepSeek V4 Pro, Claude    │
│                   Opus, Gemini 3.1 Pro]      │
│  infra_debug   → [GPT-5.5, Claude Opus,     │
│                   DeepSeek V4 Pro]           │
└────────┬────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────┐
│         OPENROUTER FUSION CALL               │
│                                              │
│  POST https://openrouter.ai/api/v1/          │
│       chat/completions                       │
│                                              │
│  {                                           │
│    "model": "openrouter/fusion",             │
│    "plugins": [{                             │
│      "id": "fusion",                         │
│      "model": "anthropic/claude-opus-4.8",   │
│      "analysis_models": [panel...]           │
│    }],                                       │
│    "messages": [                             │
│      {"role": "system", "content": "..."},   │
│      {"role": "user", "content": "..."}      │
│    ]                                         │
│  }                                           │
└────────┬────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────┐
│            JUDGE / SYNTHESIZE                │
│                                              │
│  The Fusion judge model:                     │
│  - Identifies consensus across panel         │
│  - Flags contradictions                      │
│  - Extracts unique insights                  │
│  - Identifies blind spots                    │
│  - Produces structured analysis              │
└────────┬────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────┐
│            OUTPUT                            │
│                                              │
│  Structured response:                        │
│  - Problem diagnosis                         │
│  - Proposed solution (with confidence)       │
│  - Alternative approaches                    │
│  - Risks and caveats                         │
│  - Cost report                               │
└─────────────────────────────────────────────┘

---

System Prompt Template

You are a specialist agent assembled to attack a specific novel problem
that has resisted常规 approaches. You have access to:

1. The full codebase context (provided below)
2. The project's operating constraints (AGENTS.md)
3. The specific problem statement
4. Previous attempts and their failure modes

YOUR TASK:
- Diagnose the root cause
- Propose a concrete solution
- If the solution requires changes, specify exact file paths and code
- If the problem is undecidable with current tools, explain why and
  propose what additional information or tools would be needed

CONSTRAINTS:
- Lean is the source of truth for formal claims
- No Float in compute paths (use Q0_16 or Q16_16)
- No sorry in committed code (unless with TODO(lean-port) + human sign-off)
- All new formal work goes to SilverSight (not Research Stack)

OUTPUT FORMAT:
{
  "diagnosis": "...",
  "solution": {
    "approach": "...",
    "confidence": 0.0-1.0,
    "files_to_change": [...],
    "code_snippets": {...}
  },
  "alternatives": [...],
  "risks": [...],
  "cost_estimate": "$X.XX"
}

---

Context Assembly

Before calling Fusion, the agent assembles context:

def assemble_context(problem: str) -> dict:
    # 1. Parse problem type
    problem_type = classify_problem(problem)
    # lean_proof | code_bug | architecture | math_novel | infra_debug

    # 2. Read relevant files
    files = find_relevant_files(problem)  # grep/glob based

    # 3. Extract build logs
    build_log = run_lake_build_if_lean(problem)

    # 4. Pull constraints
    constraints = read_agents_md()

    # 5. Check previous attempts
    history = search_contextstream(problem)

    return {
        "problem": problem,
        "type": problem_type,
        "files": files,
        "build_log": build_log,
        "constraints": constraints,
        "history": history,
    }

---

Cost Gate

COST_THRESHOLD = {
    "lean_proof": 0.50,      # $0.50 per invocation
    "code_bug": 0.30,        # $0.30
    "architecture": 1.00,    # $1.00 (most expensive, most valuable)
    "math_novel": 0.75,      # $0.75
    "infra_debug": 0.40,     # $0.40
}

def should_proceed(problem_type: str, estimated_cost: float) -> bool:
    threshold = COST_THRESHOLD.get(problem_type, 0.50)
    if estimated_cost > threshold * 3:
        return False  # Too expensive, escalate to human
    return True

---

MCP Server Definition

{
  "name": "break-glass",
  "description": "Last-resort multi-model panel for novel problems",
  "tools": [
    {
      "name": "break_glass",
      "description": "Assemble a focused multi-model panel to attack a problem that has resisted all other approaches. Costs 3-5× a single model call. Requires explicit 'break glass:' trigger.",
      "parameters": {
        "type": "object",
        "properties": {
          "problem": {
            "type": "string",
            "description": "The specific problem statement"
          },
          "context_files": {
            "type": "array",
            "items": {"type": "string"},
            "description": "Specific files to include in context"
          },
          "problem_type": {
            "type": "string",
            "enum": ["lean_proof", "code_bug", "architecture", "math_novel", "infra_debug"],
            "description": "Problem classification (auto-detected if omitted)"
          },
          "budget": {
            "type": "number",
            "description": "Maximum cost in USD (default: 1.00)"
          }
        },
        "required": ["problem"]
      }
    }
  ]
}

---

Example Invocation

Human: "break glass: cleanMerge_preservesGap sorry — I've tried native_decide, canonicalize+simp, and exhaustive list match. The List.zip/filter/all terms are too large for simp to reduce."

Agent response:

DIAGNOSIS: The bridge lemma requires showing that verifySpectralGap on an
8-element Q16_16 list equals boolGapPat on the boolean pattern. The simp
tactic can't reduce List.zip (List.range 8) [a0,...,a7] |>.filter |>.map
|.all to the equivalent Bool expression because intermediate terms exceed
simp's working memory.

SOLUTION: Define a @[reducible] helper that mirrors verifySpectralGap but
on Fin 8 → Bool, prove it equals boolGapPat by native_decide, then show
verifySpectralGap = helper ∘ (· != 0) by pattern-matching on 8-element
lists and using canonicalize_ne_zero.

[exact code provided]

CONFIDENCE: 0.85
ALTERNATIVES:
  1. Custom simp lemma for 8-element List.zip (lower confidence)
  2. Rewrite verifySpectralGap to use Fin 8 directly (invasive)
RISKS: The @[reducible] approach may cause simp slowdowns elsewhere
COST: $0.47

---

Integration Points

1. MCP server — break-glass tool in .mcp.json
2. Skill — break-glass skill that loads the system prompt
3. ContextStream — logs every invocation for cost tracking
4. AGENTS.md — documents the trigger protocol
5. Cost tracking — ContextStream memory events for each invocation

---

Safety

• Rate limit: Max 3 invocations per session
• Cost cap: $5.00 per session (configurable)
• Human gate: If estimated cost > $2.00, require human confirmation
• Audit trail: Every invocation logged to ContextStream with cost, problem, and outcome