# ADR-105: MCP Agent Loop Governance

**狀態**: Accepted  
**日期**: 2026-05-01  
**範圍**: MCP audit, Agent Loop, OpenClaw/NemoTron/Hermes/ElephantAlpha tool permissions

## 背景

AWOOOI 已有 MCP provider registry、K8s/SSH/Prometheus/Database/Grafana/RAG/Filesystem 等 provider、PreDecisionInvestigator、EvidenceSnapshot、PostExecutionVerifier。缺口不是「從零安裝 MCP」，而是：

- MCP 呼叫沒有統一 audit trail 與每日統計。
- PreDecisionInvestigator 是 Python pre-gathering 模式，LLM 看到結果但看不到 tool_use 過程。
- 不同 AI Agent 沒有可驗證的工具權限邊界。
- LLM retry storm 修掉後，需要讓真正的新 incident 能用 Agent Loop 深查，而不是回到靜態 prompt。

## 決策

### D1 — 保留 pre-gathering，新增 Agent Loop

PreDecisionInvestigator 仍是穩定 fallback。Agent Loop 作為 provider capability 漸進接入：

```text
Alert -> PreDecisionInvestigator -> EvidenceSnapshot -> LLM text decision
Alert -> Agent Loop -> LLM tool_use -> MCP tool_result -> Final Decision
```

任何 Agent Loop 超過 `max_iterations`、provider 不支援 tool_use、或工具權限不足時，必須降級回既有 pre-gathering / rule-first / Playbook RAG 路徑。

### D2 — 四 Agent 工具權限矩陣

| Agent | 允許 | 禁止 |
|-------|------|------|
| OpenClaw | 所有已註冊 MCP tool，由既有 safety gates 控制執行 | 無額外禁用 |
| NemoTron | Prometheus/Grafana/SignOz，K8s read-only | K8s restart/delete/scale/apply/patch |
| Hermes | Database、RAG、Filesystem、Prometheus | K8s/SSH 執行類操作 |
| ElephantAlpha | 全部 read-only | 任何寫入/通知/執行操作 |

權限定義在 `apps/api/src/services/ai_providers/permissions.py`，provider schema 轉換前必須先過濾。

### D3 — 統一 MCP audit

所有 registry provider 與 PDI tool registry provider 都包成 audited provider，寫入：

- `mcp_audit_log`
- `mcp_daily_stats`

`incident_id` 使用 `VARCHAR(64)`，因為 AWOOOI incident id 是 `INC-*` 字串，不是 UUID。Audit 必須包含 `agent_role`、`session_id`、`flywheel_node`、provider/tool、input/output、latency、success/error。

### D4 — MCP RAG 不獨立建 DB

內部 MCP RAG 沿用現有 PostgreSQL + pgvector + Redis hot cache：

- `knowledge_entries`
- `rag_chunks`
- `playbook_embeddings`
- existing KMWriter / KnowledgeRAG / PlaybookRAG

不另建獨立資料庫。原因：一致性、備份、incident/playbook join、權限治理都在同一 Postgres 邊界內已經存在。只有當向量資料量、查詢延遲、或多租戶隔離需要獨立擴展時，才評估外移專用 vector DB。

## 落地順序

1. P0: audit schema、agent_role、權限矩陣、tool schema、AgentToolExecutor。
2. P1: Claude/Ollama provider 接 `analyze_with_tools()`，但 DecisionManager 先 feature flag，不直接切主路徑。
3. P2: OpenClaw/NemoTron/Hermes/ElephantAlpha 逐一接線，先 read-only / diagnose，再開執行類工具。
4. P3: Langfuse spans、Grafana MCP dashboard、audit replay。

## 2026-05-01 P1 Canary

OpenClaw 先接 read-only shadow investigation，而不是直接替換主決策：

- Feature flag：`ENABLE_OPENCLAW_AGENT_LOOP_SHADOW`
- 輪數上限：`OPENCLAW_AGENT_LOOP_MAX_ITERATIONS`（prod canary 設 2）
- 觸發點：`OpenClawService.generate_incident_proposal_with_tools()` 原 proposal 成功後
- 允許工具：Kubernetes / Prometheus / SignOz / Database / RAG / Grafana 的 read-only tools
- Provider：本地 Ollama 優先，不新增 Gemini/Claude 付費呼叫
- 影響面：只附加 `agent_loop_shadow` metadata，不覆蓋 `action`、`risk_level`、`confidence` 或 Nemotron tool result
- Structured metadata：shadow raw response 需正規化為 `agent_loop_shadow.structured`，包含 `root_cause_check`、`evidence_used`、`confidence_delta`、`missing_evidence`、`human_or_ai_next_step`、`parse_status`
- Confidence delta：canary 階段只可記錄 0 到 -0.15 的保守 metadata，正值一律歸零；任何 score 或 auto-execute gate 變更需另開 ADR/Logbook 並通過 production audit
- 失敗策略：log warning 後回到既有 proposal / Nemotron / Playbook 路徑

## 驗收

- `mcp_audit_log` 24h call count > 0。
- 每筆 Agent Loop tool_use 有 `agent_role`。
- NemoTron / ElephantAlpha 無法取得 K8s 寫入工具。
- LLM ghost-loop 不因 Agent Loop 重啟：仍受 Alertmanager in-flight lock、stable cache、provider circuit breaker、max_iterations 控制。