From 69f056e4a7b4f3f8c2400ba98d5d963dcac40f27 Mon Sep 17 00:00:00 2001
From: AhmadHammad21 <ahmedhammad8765@gmail.com>
Date: Fri, 22 May 2026 15:56:26 +0300
Subject: [PATCH 1/3] feat(llm): add Claude Code subscription backend and
 isolate AWS into providers

- Auto-detect the Claude Code CLI and use its subscription OAuth login as the
  Anthropic LLM backend (no API key needed). LiteLLM handles sk-ant-oat tokens;
  system prompts are shaped with the required Claude Code identity block.
- Add agent/llm/ package: backend resolver + pluggable detector registry.
- Surface the active LLM backend in the init wizard and Settings.
- Restructure cloud-specific code under providers/ behind a CloudProvider
  protocol; move AWS tools/context/permissions/poller/events into providers/aws/.
- Add CLOUD_PROVIDER setting (aws|azure|gcp); azure/gcp are stubs.
---
 .env.example                                  |  10 ++
 docs/llm_providers.md                         |  18 +++
 frontend/src/components/LlmBackendCard.tsx    |  50 ++++++
 frontend/src/pages/InitPage.tsx               |  24 ++-
 frontend/src/pages/SettingsPage.tsx           |  12 +-
 frontend/src/types.ts                         |   9 ++
 src/agent/core.py                             |  55 ++++---
 src/agent/llm/__init__.py                     |  23 +++
 src/agent/llm/backend.py                      | 149 ++++++++++++++++++
 src/agent/llm/detectors/__init__.py           |  14 ++
 src/agent/llm/detectors/base.py               |  34 ++++
 src/agent/llm/detectors/claude_code.py        | 131 +++++++++++++++
 src/agent/llm/identity.py                     |  31 ++++
 src/agent/summarizer.py                       |   8 +-
 src/api/app.py                                |   8 +-
 src/api/routers/chat.py                       |   5 +-
 src/api/routers/init.py                       |  11 +-
 src/api/routers/settings.py                   |   3 +-
 src/cli/ask.py                                |  11 +-
 src/cli/report.py                             |   2 +-
 src/config/appsettings.py                     |   9 ++
 src/providers/__init__.py                     |  24 +++
 src/providers/aws/__init__.py                 |  47 ++++++
 .../aws/context.py}                           |   0
 .../aws}/event_consumer.py                    |   2 +-
 src/{agent => providers/aws}/event_infra.py   |   0
 .../aws/permissions.py}                       |   0
 src/{agent => providers/aws}/poller.py        |   6 +-
 src/providers/aws/tools/__init__.py           |   1 +
 src/{ => providers/aws}/tools/cloudtrail.py   |   0
 src/{ => providers/aws}/tools/cloudwatch.py   |   0
 src/{ => providers/aws}/tools/ec2.py          |   0
 src/{ => providers/aws}/tools/ecs.py          |   0
 src/{ => providers/aws}/tools/iam.py          |   0
 src/{ => providers/aws}/tools/lambda_.py      |   0
 src/{ => providers/aws}/tools/rds.py          |   0
 src/providers/azure/__init__.py               |  35 ++++
 src/providers/base.py                         |  36 +++++
 src/providers/gcp/__init__.py                 |  35 ++++
 tests/integration/test_dlq_logic.py           |  18 +--
 tests/integration/test_poller.py              |   8 +-
 tests/test_tools/test_cloudwatch.py           |   2 +-
 tests/test_tools/test_ecs.py                  |   2 +-
 tests/test_tools/test_lambda.py               |   2 +-
 tests/test_tools/test_rds.py                  |   2 +-
 45 files changed, 770 insertions(+), 67 deletions(-)
 create mode 100644 frontend/src/components/LlmBackendCard.tsx
 create mode 100644 src/agent/llm/__init__.py
 create mode 100644 src/agent/llm/backend.py
 create mode 100644 src/agent/llm/detectors/__init__.py
 create mode 100644 src/agent/llm/detectors/base.py
 create mode 100644 src/agent/llm/detectors/claude_code.py
 create mode 100644 src/agent/llm/identity.py
 create mode 100644 src/providers/__init__.py
 create mode 100644 src/providers/aws/__init__.py
 rename src/{agent/context_collectors.py => providers/aws/context.py} (100%)
 rename src/{agent => providers/aws}/event_consumer.py (99%)
 rename src/{agent => providers/aws}/event_infra.py (100%)
 rename src/{agent/permission_checker.py => providers/aws/permissions.py} (100%)
 rename src/{agent => providers/aws}/poller.py (98%)
 create mode 100644 src/providers/aws/tools/__init__.py
 rename src/{ => providers/aws}/tools/cloudtrail.py (100%)
 rename src/{ => providers/aws}/tools/cloudwatch.py (100%)
 rename src/{ => providers/aws}/tools/ec2.py (100%)
 rename src/{ => providers/aws}/tools/ecs.py (100%)
 rename src/{ => providers/aws}/tools/iam.py (100%)
 rename src/{ => providers/aws}/tools/lambda_.py (100%)
 rename src/{ => providers/aws}/tools/rds.py (100%)
 create mode 100644 src/providers/azure/__init__.py
 create mode 100644 src/providers/base.py
 create mode 100644 src/providers/gcp/__init__.py

diff --git a/.env.example b/.env.example
index 95e5a1b..8914953 100644
--- a/.env.example
+++ b/.env.example
@@ -3,6 +3,12 @@
 LLM_MODEL=openrouter/openai/gpt-4o
 OPENROUTER_API_KEY=sk-or-...
 
+# Claude Code auto-detection (default: true)
+# When enabled and LLM_MODEL/API keys are not explicitly set, the app will detect
+# the Claude Code CLI (~/.claude/) and use it as the Anthropic LLM backend automatically.
+# Set to false to disable.
+# CLAUDE_CODE_AUTODETECT=true
+
 # Anthropic direct
 # LLM_MODEL=anthropic/claude-3-5-sonnet-20241022
 # ANTHROPIC_API_KEY=sk-ant-...
@@ -24,6 +30,10 @@ OPENROUTER_API_KEY=sk-or-...
 # LLM_API_BASE=https://your-endpoint/v1
 # LLM_API_KEY=your-key
 
+# Cloud provider — selects the active provider (aws | azure | gcp). Default: aws.
+# Azure and GCP are stubs; only aws is implemented today.
+# CLOUD_PROVIDER=aws
+
 # AWS (use IAM role or explicit keys)
 AWS_REGION=us-east-1
 AWS_PROFILE=devops-agent-readonly   # optional — use named profile (local dev)
diff --git a/docs/llm_providers.md b/docs/llm_providers.md
index 4a2f070..8b57f18 100644
--- a/docs/llm_providers.md
+++ b/docs/llm_providers.md
@@ -22,6 +22,24 @@ LiteLLM routes to Anthropic API  →  same agent graph, same tools
 
 ## Supported providers (examples)
 
+### Claude Code (zero-config, auto-detected)
+
+If you have [Claude Code](https://claude.ai/code) installed and authenticated, OpenDevOps detects it automatically — no `.env` changes required.
+
+**How it works:**
+1. On startup, the app checks if the `claude` CLI is in your PATH
+2. It reads `~/.claude/settings.json` for your configured model slot
+3. It picks up your auth from `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or Claude Code's OAuth credential file
+
+The active LLM backend is shown in **Settings → Environment** and in the **setup wizard**.
+
+To disable auto-detection:
+```bash
+CLAUDE_CODE_AUTODETECT=false
+```
+
+---
+
 ### OpenRouter (default — 200+ models via one key)
 ```bash
 LLM_MODEL=openrouter/openai/gpt-4o
diff --git a/frontend/src/components/LlmBackendCard.tsx b/frontend/src/components/LlmBackendCard.tsx
new file mode 100644
index 0000000..bd3fa7c
--- /dev/null
+++ b/frontend/src/components/LlmBackendCard.tsx
@@ -0,0 +1,50 @@
+import { CheckCircle, XCircle, AlertTriangle, Cpu } from 'lucide-react';
+import { cn } from '../lib/utils';
+import type { LlmBackendInfo } from '../types';
+
+interface Props {
+  backend: LlmBackendInfo;
+  className?: string;
+}
+
+const SOURCE_STYLE: Record<string, { color: string; bg: string; border: string }> = {
+  claude_code:         { color: 'text-amber-700 dark:text-amber-300',  bg: 'bg-amber-50 dark:bg-amber-500/10',  border: 'border-amber-200 dark:border-amber-500/20' },
+  anthropic:           { color: 'text-orange-700 dark:text-orange-300', bg: 'bg-orange-50 dark:bg-orange-500/10', border: 'border-orange-200 dark:border-orange-500/20' },
+  openrouter:          { color: 'text-purple-700 dark:text-purple-300', bg: 'bg-purple-50 dark:bg-purple-500/10', border: 'border-purple-200 dark:border-purple-500/20' },
+  openai:              { color: 'text-green-700 dark:text-green-300',   bg: 'bg-green-50 dark:bg-green-500/10',   border: 'border-green-200 dark:border-green-500/20' },
+  groq:                { color: 'text-blue-700 dark:text-blue-300',     bg: 'bg-blue-50 dark:bg-blue-500/10',     border: 'border-blue-200 dark:border-blue-500/20' },
+  custom:              { color: 'text-indigo-700 dark:text-indigo-300', bg: 'bg-indigo-50 dark:bg-indigo-500/10', border: 'border-indigo-200 dark:border-indigo-500/20' },
+  claude_code_no_auth: { color: 'text-amber-700 dark:text-amber-300',  bg: 'bg-amber-50 dark:bg-amber-500/10',  border: 'border-amber-200 dark:border-amber-500/20' },
+  default:             { color: 'text-gray-500 dark:text-[#71717A]',   bg: 'bg-gray-50 dark:bg-[#18181B]',      border: 'border-gray-200 dark:border-[#27272A]' },
+};
+
+function StatusIcon({ configured, source }: { configured: boolean; source: string }) {
+  if (source === 'claude_code_no_auth') return <AlertTriangle size={14} className="text-amber-500 shrink-0" />;
+  if (source === 'default')             return <XCircle       size={14} className="text-gray-400 shrink-0" />;
+  if (configured)                       return <CheckCircle   size={14} className="text-emerald-500 shrink-0" />;
+  return                                       <XCircle       size={14} className="text-red-500 shrink-0" />;
+}
+
+export default function LlmBackendCard({ backend, className }: Props) {
+  const style = SOURCE_STYLE[backend.source] ?? SOURCE_STYLE.default;
+
+  return (
+    <div className={cn('rounded-xl border p-4', style.bg, style.border, className)}>
+      <div className="flex items-start gap-3">
+        <div className={cn('mt-0.5 rounded-lg p-1.5', style.bg)}>
+          <Cpu size={14} className={style.color} />
+        </div>
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center gap-2 mb-0.5">
+            <StatusIcon configured={backend.configured} source={backend.source} />
+            <span className={cn('text-sm font-semibold', style.color)}>{backend.display_name}</span>
+          </div>
+          <p className="text-xs text-gray-500 dark:text-[#71717A] font-mono truncate">{backend.detail}</p>
+          {backend.configured && (
+            <p className="text-xs text-gray-400 dark:text-[#52525B] mt-1 font-mono truncate">{backend.model}</p>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/frontend/src/pages/InitPage.tsx b/frontend/src/pages/InitPage.tsx
index e07c18c..5688197 100644
--- a/frontend/src/pages/InitPage.tsx
+++ b/frontend/src/pages/InitPage.tsx
@@ -4,6 +4,8 @@ import { ArrowRight, ArrowLeft, Loader2, Terminal, Eye, EyeOff, CheckCircle, XCi
 import { cn } from '../lib/utils';
 import { useAuth } from '../context/AuthContext';
 import { apiFetch } from '../lib/api';
+import LlmBackendCard from '../components/LlmBackendCard';
+import type { LlmBackendInfo } from '../types';
 
 const inp = 'w-full text-base text-gray-900 dark:text-white bg-gray-50 dark:bg-[#18181B] border border-gray-200 dark:border-[#27272A] rounded-xl px-4 py-3.5 outline-none focus:border-indigo-500 dark:focus:border-indigo-400 focus:ring-2 focus:ring-indigo-500/10 transition-all placeholder:text-gray-400 dark:placeholder:text-[#52525B]';
 
@@ -56,7 +58,8 @@ export default function InitPage() {
   const [showPw,   setShowPw]   = useState(false);
 
   // Step 2
-  const [region,   setRegion]   = useState('us-east-1');
+  const [region,      setRegion]      = useState('us-east-1');
+  const [llmBackend,  setLlmBackend]  = useState<LlmBackendInfo | null>(null);
 
   // Step 3
   const [perms,    setPerms]    = useState<Record<string, PermResult>>({});
@@ -77,6 +80,7 @@ export default function InitPage() {
       .then(r => r.json())
       .then(d => {
         setRegion(d.aws_region || 'us-east-1');
+        if (d.llm_backend) setLlmBackend(d.llm_backend as LlmBackendInfo);
         if (d.initialized && (d.has_user || !d.auth_enabled)) {
           navigate('/', { replace: true });
           return;
@@ -252,9 +256,25 @@ export default function InitPage() {
           {step === 2 && (
             <>
               <h1 className="text-3xl font-bold text-gray-900 dark:text-white tracking-tight mb-3">AWS Configuration</h1>
-              <p className="text-lg text-gray-500 dark:text-[#A1A1AA] mb-10 leading-relaxed">
+              <p className="text-lg text-gray-500 dark:text-[#A1A1AA] mb-6 leading-relaxed">
                 Configure the AWS region and optional SNS topic for alert delivery.
               </p>
+
+              {/* LLM Backend status */}
+              {llmBackend && (
+                <div className="mb-8">
+                  <p className="text-sm font-medium text-gray-700 dark:text-[#D4D4D8] mb-2">LLM Backend</p>
+                  <LlmBackendCard backend={llmBackend} />
+                  {!llmBackend.configured && (
+                    <p className="mt-2 text-xs text-gray-400 dark:text-[#52525B]">
+                      You can set <code className="bg-gray-100 dark:bg-[#27272A] px-1 rounded">LLM_MODEL</code> and an API key in <code className="bg-gray-100 dark:bg-[#27272A] px-1 rounded">.env</code>, or install{' '}
+                      <a href="https://claude.ai/code" target="_blank" rel="noopener noreferrer" className="text-indigo-500 dark:text-[#818CF8] hover:underline">Claude Code</a>{' '}
+                      for zero-config setup. See <a href="https://github.com/AhmadHammad21/OpenDevOps/blob/main/docs/llm_providers.md" target="_blank" rel="noopener noreferrer" className="text-indigo-500 dark:text-[#818CF8] hover:underline">docs/llm_providers.md</a>.
+                    </p>
+                  )}
+                </div>
+              )}
+
               <div className="space-y-5">
                 <div>
                   <label className="block text-sm font-medium text-gray-700 dark:text-[#D4D4D8] mb-2">
diff --git a/frontend/src/pages/SettingsPage.tsx b/frontend/src/pages/SettingsPage.tsx
index 19256a6..c1d60bd 100644
--- a/frontend/src/pages/SettingsPage.tsx
+++ b/frontend/src/pages/SettingsPage.tsx
@@ -6,10 +6,12 @@ import { apiFetch } from '../lib/api';
 import { useAuth } from '../context/AuthContext';
 import { useTheme } from '../context/ThemeContext';
 import { cn } from '../lib/utils';
+import LlmBackendCard from '../components/LlmBackendCard';
+import type { LlmBackendInfo } from '../types';
 
 interface EnvVar   { key: string; value: string; secret: boolean }
 interface AgentVar { key: string; label: string; value: string; hint: string }
-interface SettingsData { env: EnvVar[]; agent: AgentVar[] }
+interface SettingsData { env: EnvVar[]; agent: AgentVar[]; llm_backend?: LlmBackendInfo }
 interface PermResult   { passed: boolean | null; error: string | null }
 
 type Tab = 'env' | 'agent' | 'integrations' | 'aws' | 'preferences';
@@ -225,6 +227,13 @@ export default function SettingsPage() {
 
         {/* Environment tab */}
         {tab === 'env' && (
+          <>
+          {data?.llm_backend && (
+            <div className="mb-5">
+              <p className="text-[11px] font-semibold text-gray-400 dark:text-[#64748B] uppercase tracking-[0.07em] mb-2">LLM Backend</p>
+              <LlmBackendCard backend={data.llm_backend} />
+            </div>
+          )}
           <div className="bg-white dark:bg-[#18181C] border border-gray-200 dark:border-[#27272F] rounded-lg overflow-hidden shadow-[0_1px_2px_rgba(0,0,0,0.04)]">
             <div className="px-4 py-[11px] border-b border-gray-200 dark:border-[#27272F] bg-gray-50 dark:bg-[#1E1E24]">
               <span className="text-[11px] font-semibold text-gray-400 dark:text-[#64748B] uppercase tracking-[0.07em]">Environment Variables</span>
@@ -252,6 +261,7 @@ export default function SettingsPage() {
               <div className="px-4 py-6 text-[13px] text-gray-400 dark:text-[#64748B] text-center">Loading…</div>
             )}
           </div>
+          </>
         )}
 
         {/* Agent config tab */}
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index c93d960..c430845 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -12,6 +12,15 @@ export interface Usage {
   cost_usd?: number;
 }
 
+export interface LlmBackendInfo {
+  source: string;       // claude_code | anthropic | openrouter | openai | groq | custom | default
+  model: string;
+  display_name: string;
+  provider: string;
+  configured: boolean;
+  detail: string;
+}
+
 export interface UserMessage {
   id: string;
   role: 'user';
diff --git a/src/agent/core.py b/src/agent/core.py
index 3935d10..c95eaa1 100644
--- a/src/agent/core.py
+++ b/src/agent/core.py
@@ -12,34 +12,27 @@
 from models.agent import Confidence, Investigation, InvestigationResult, RootCauseCategory
 from agent.prompts import SYSTEM_PROMPT
 from loguru import logger
+from providers import get_active_provider
 from tools._cap import with_cap
-from tools.cloudtrail import ALL_CLOUDTRAIL_TOOLS
-from tools.cloudwatch import ALL_CLOUDWATCH_TOOLS
-from tools.ec2 import ALL_EC2_TOOLS
-from tools.ecs import ALL_ECS_TOOLS
 from tools.bash_tool import ALL_BASH_TOOLS
 from tools.final_answer import ALL_FINAL_ANSWER_TOOLS
 from tools.history import ALL_HISTORY_TOOLS
-from tools.iam import ALL_IAM_TOOLS
-from tools.lambda_ import ALL_LAMBDA_TOOLS
-from tools.rds import ALL_RDS_TOOLS
 from tools.skills import ALL_SKILL_TOOLS
 
-ALL_TOOLS = (
-    ALL_CLOUDWATCH_TOOLS
-    + ALL_CLOUDTRAIL_TOOLS
-    + ALL_ECS_TOOLS
-    + ALL_LAMBDA_TOOLS
-    + ALL_EC2_TOOLS
-    + ALL_RDS_TOOLS
-    + ALL_IAM_TOOLS
-    + ALL_HISTORY_TOOLS
-    + ALL_BASH_TOOLS
-    + ALL_SKILL_TOOLS
-    + ALL_FINAL_ANSWER_TOOLS
-)
+# Cloud-agnostic tools available regardless of provider.
+SHARED_TOOLS = ALL_HISTORY_TOOLS + ALL_BASH_TOOLS + ALL_SKILL_TOOLS + ALL_FINAL_ANSWER_TOOLS
+
+# Active provider's cloud tools + shared tools. Provider is selected by CLOUD_PROVIDER.
+ALL_TOOLS = get_active_provider().tools() + SHARED_TOOLS
 
 _agent = None
+_active_model: str | None = None
+
+
+def get_active_model() -> str:
+    """Return the resolved LLM model string (may differ from settings.llm_model when
+    Claude Code auto-detection overrides the default)."""
+    return _active_model or settings.llm_model
 
 
 def _run_async(coro: Any) -> Any:
@@ -55,19 +48,33 @@ def _run_async(coro: Any) -> Any:
     raise RuntimeError("Cannot run synchronous agent call inside an active event loop")
 
 
+def _build_system_prompt(api_key: str | None) -> Any:
+    """Return the system prompt for create_deep_agent — a SystemMessage with the
+    Claude Code identity block for subscription OAuth tokens, else a plain string."""
+    from agent.llm import shape_system_content
+    content = shape_system_content(SYSTEM_PROMPT, api_key)
+    if isinstance(content, list):
+        from langchain_core.messages import SystemMessage
+        return SystemMessage(content=content)
+    return content
+
+
 def init_agent(checkpointer: Any) -> None:
     """Create the agent with the given checkpointer. Called once during app startup."""
-    global _agent
+    global _agent, _active_model
+    from agent.llm import resolve_model_and_key
+    model_name, api_key = resolve_model_and_key()
+    _active_model = model_name
     model = ChatLiteLLM(
-        model=settings.llm_model,
+        model=model_name,
         api_base=settings.llm_api_base or None,
-        api_key=settings.llm_api_key or None,
+        api_key=api_key,
     )
     tools = [with_cap(t) for t in ALL_TOOLS] if settings.tool_response_max_chars > 0 else ALL_TOOLS
     _agent = create_deep_agent(
         model=model,
         tools=tools,
-        system_prompt=SYSTEM_PROMPT,
+        system_prompt=_build_system_prompt(api_key),
         checkpointer=checkpointer,
     )
 
diff --git a/src/agent/llm/__init__.py b/src/agent/llm/__init__.py
new file mode 100644
index 0000000..9702c92
--- /dev/null
+++ b/src/agent/llm/__init__.py
@@ -0,0 +1,23 @@
+"""LLM backend resolution and provider detection.
+
+Public API:
+  - resolve_model_and_key(): (model, api_key) for ChatLiteLLM initialisation
+  - get_backend_info():      a description of the active backend for the UI
+  - shape_system_content():  provider-specific system-prompt shaping
+"""
+
+from agent.llm.backend import LlmBackendInfo, get_backend_info, resolve_model_and_key
+from agent.llm.identity import (
+    CLAUDE_CODE_IDENTITY,
+    is_subscription_token,
+    shape_system_content,
+)
+
+__all__ = [
+    "LlmBackendInfo",
+    "get_backend_info",
+    "resolve_model_and_key",
+    "CLAUDE_CODE_IDENTITY",
+    "is_subscription_token",
+    "shape_system_content",
+]
diff --git a/src/agent/llm/backend.py b/src/agent/llm/backend.py
new file mode 100644
index 0000000..b705c06
--- /dev/null
+++ b/src/agent/llm/backend.py
@@ -0,0 +1,149 @@
+"""Resolve and describe the active LLM backend from all available configuration sources.
+
+Priority order (first match wins):
+  1. LLM_API_BASE set                          → custom endpoint
+  2. ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN  → anthropic (direct)
+  3. OPENROUTER_API_KEY + openrouter model     → openrouter
+  4. Other explicit provider key + LLM_MODEL   → that provider
+  5. Installed CLI detector (e.g. Claude Code) → subscription login
+  6. Nothing                                   → unconfigured
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import TypedDict
+
+from config import settings
+from agent.llm.detectors import ALL_DETECTORS
+
+_DATE_SUFFIX = re.compile(r"-\d{8}$")
+
+
+class LlmBackendInfo(TypedDict):
+    source: str       # claude_code | anthropic | openrouter | openai | groq | custom | default
+    model: str        # active LiteLLM model string
+    display_name: str # human-readable source name shown in the UI
+    provider: str     # anthropic | openai | openrouter | groq | ollama | custom
+    configured: bool  # True when valid auth is present
+    detail: str       # friendly model name or setup hint
+
+
+def _strip_date(model: str) -> str:
+    return _DATE_SUFFIX.sub("", model.split("/")[-1])
+
+
+def _provider_of(model: str) -> str:
+    if model.startswith("anthropic/"):
+        return "anthropic"
+    if "openrouter" in model:
+        return "openrouter"
+    if model.startswith("openai/") or "gpt" in model:
+        return "openai"
+    if model.startswith("groq/"):
+        return "groq"
+    if model.startswith("ollama/"):
+        return "ollama"
+    return "custom"
+
+
+def _detector_backend() -> LlmBackendInfo | None:
+    """Consult CLI detectors in registry order; return the first installed one."""
+    for det in ALL_DETECTORS:
+        if not det.enabled or not det.is_installed():
+            continue
+        resolved = det.resolve()
+        if resolved:
+            model, _ = resolved
+            return LlmBackendInfo(
+                source=det.name,
+                model=model,
+                display_name=f"{det.label} (auto-detected)",
+                provider=det.provider,
+                configured=True,
+                detail=_strip_date(model),
+            )
+        st = det.status()
+        return LlmBackendInfo(
+            source=f"{det.name}_no_auth",
+            model=st.get("model") or settings.llm_model,
+            display_name=f"{det.label} (not authenticated)",
+            provider=det.provider,
+            configured=False,
+            detail=st.get("hint") or "Authenticate the CLI or set an API key",
+        )
+    return None
+
+
+def get_backend_info() -> LlmBackendInfo:
+    """Return a description of the active LLM backend for /api/settings and /api/init/status."""
+    model = settings.llm_model
+    api_base = settings.llm_api_base or None
+    explicit_model = bool(os.environ.get("LLM_MODEL"))
+
+    # Custom endpoint always takes precedence
+    if api_base:
+        return LlmBackendInfo(
+            source="custom", model=model, display_name="Custom endpoint",
+            provider="custom", configured=True, detail=api_base,
+        )
+
+    # Anthropic direct (env key)
+    if os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN"):
+        source, label = "anthropic", "Anthropic API key"
+        if explicit_model and "anthropic" not in model:
+            source = _provider_of(model)
+            label = source.title() + " (via .env)"
+        return LlmBackendInfo(
+            source=source, model=model, display_name=label,
+            provider=_provider_of(model), configured=True, detail=_strip_date(model),
+        )
+
+    # OpenRouter key
+    if settings.openrouter_api_key and "openrouter" in model:
+        return LlmBackendInfo(
+            source="openrouter", model=model, display_name="OpenRouter",
+            provider="openrouter", configured=True, detail=_strip_date(model),
+        )
+
+    # Any other explicit provider key (OPENAI_API_KEY, GROQ_API_KEY, …)
+    if explicit_model:
+        provider = _provider_of(model)
+        has_key = any(
+            os.environ.get(k)
+            for k in ("OPENAI_API_KEY", "GROQ_API_KEY", "COHERE_API_KEY", "MISTRAL_API_KEY")
+        )
+        if has_key:
+            return LlmBackendInfo(
+                source=provider, model=model, display_name=provider.title() + " (via .env)",
+                provider=provider, configured=True, detail=_strip_date(model),
+            )
+
+    # Installed CLI detector (subscription login)
+    detected = _detector_backend()
+    if detected:
+        return detected
+
+    return LlmBackendInfo(
+        source="default", model=model, display_name="Not configured",
+        provider=_provider_of(model), configured=False,
+        detail="Set LLM_MODEL and an API key in .env, or install a supported CLI (e.g. Claude Code)",
+    )
+
+
+def resolve_model_and_key() -> tuple[str, str | None]:
+    """Return (litellm_model_string, api_key_or_None) for ChatLiteLLM initialisation.
+
+    Called from init_agent() in core.py and other LLM call sites.
+    """
+    info = get_backend_info()
+
+    # If a CLI detector supplied the backend, use its resolved (model, key)
+    for det in ALL_DETECTORS:
+        if info["source"] == det.name:
+            resolved = det.resolve()
+            if resolved:
+                return resolved
+
+    return info["model"], (settings.llm_api_key or None)
diff --git a/src/agent/llm/detectors/__init__.py b/src/agent/llm/detectors/__init__.py
new file mode 100644
index 0000000..a9f217d
--- /dev/null
+++ b/src/agent/llm/detectors/__init__.py
@@ -0,0 +1,14 @@
+"""Registry of CLI-based LLM backend detectors, consulted in priority order.
+
+To add a provider: implement the LlmDetector protocol in a new module here and
+append an instance to ALL_DETECTORS.
+"""
+
+from agent.llm.detectors.base import LlmDetector
+from agent.llm.detectors.claude_code import ClaudeCodeDetector
+
+ALL_DETECTORS: list[LlmDetector] = [
+    ClaudeCodeDetector(),
+]
+
+__all__ = ["LlmDetector", "ALL_DETECTORS", "ClaudeCodeDetector"]
diff --git a/src/agent/llm/detectors/base.py b/src/agent/llm/detectors/base.py
new file mode 100644
index 0000000..835d2dd
--- /dev/null
+++ b/src/agent/llm/detectors/base.py
@@ -0,0 +1,34 @@
+"""Detector protocol for CLI-based LLM backends.
+
+A detector recognises a locally-installed CLI tool (Claude Code, Gemini CLI, Codex…)
+and reuses its existing login as an LLM backend — no API key required. New providers
+are added by implementing this protocol and registering the class in ``__init__.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LlmDetector(Protocol):
+    name: str      # stable id used as the backend `source`, e.g. "claude_code"
+    label: str     # brand name shown in the UI, e.g. "Claude Code"
+    provider: str  # litellm provider family, e.g. "anthropic"
+
+    @property
+    def enabled(self) -> bool:
+        """Whether auto-detection for this provider is turned on (via settings)."""
+        ...
+
+    def is_installed(self) -> bool:
+        """True if the CLI tool is present on this machine."""
+        ...
+
+    def resolve(self) -> tuple[str, str] | None:
+        """Return (litellm_model, api_key) when installed AND authenticated, else None."""
+        ...
+
+    def status(self) -> dict:
+        """Rich status for the settings / init UI (installed, authenticated, model, hint…)."""
+        ...
diff --git a/src/agent/llm/detectors/claude_code.py b/src/agent/llm/detectors/claude_code.py
new file mode 100644
index 0000000..ba5d0f1
--- /dev/null
+++ b/src/agent/llm/detectors/claude_code.py
@@ -0,0 +1,131 @@
+"""Claude Code CLI detector — reuses the local subscription login as an Anthropic backend.
+
+Auth resolution order:
+  1. ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN environment variables
+  2. Claude Code's OAuth access token (~/.claude/.credentials.json)
+
+LiteLLM (>=1.83) detects ``sk-ant-oat`` tokens and uses Authorization: Bearer + the
+OAuth beta header automatically, so the subscription login works with no API key.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+
+from loguru import logger
+
+from config import settings
+
+_SETTINGS_PATH = Path.home() / ".claude" / "settings.json"
+_CREDS_PATH = Path.home() / ".claude" / ".credentials.json"
+
+# Claude Code model slot names → LiteLLM model strings.
+# Includes both short aliases ("sonnet") and full slot names ("claude-sonnet-4-5").
+_MODEL_SLOTS: dict[str, str] = {
+    # Short aliases used by Claude Code settings.json
+    "sonnet":  "anthropic/claude-sonnet-4-6",
+    "opus":    "anthropic/claude-opus-4-7",
+    "haiku":   "anthropic/claude-haiku-4-5-20251001",
+    # Full slot names
+    "claude-opus-4-7":            "anthropic/claude-opus-4-7",
+    "claude-sonnet-4-6":          "anthropic/claude-sonnet-4-6",
+    "claude-haiku-4-5":           "anthropic/claude-haiku-4-5-20251001",
+    "claude-opus-4-5":            "anthropic/claude-opus-4-5-20251001",
+    "claude-opus-4":              "anthropic/claude-opus-4-20251101",
+    "claude-sonnet-4-5":          "anthropic/claude-sonnet-4-5-20251024",
+    "claude-sonnet-4":            "anthropic/claude-sonnet-4-20251120",
+    "claude-3-5-sonnet-20241022": "anthropic/claude-3-5-sonnet-20241022",
+    "claude-3-5-haiku-20241022":  "anthropic/claude-3-5-haiku-20241022",
+    "claude-3-opus-20240229":     "anthropic/claude-3-opus-20240229",
+}
+_DEFAULT_MODEL = "anthropic/claude-sonnet-4-6"
+
+
+class ClaudeCodeDetector:
+    name = "claude_code"
+    label = "Claude Code"
+    provider = "anthropic"
+
+    @property
+    def enabled(self) -> bool:
+        return settings.claude_code_autodetect
+
+    def is_installed(self) -> bool:
+        return shutil.which("claude") is not None
+
+    def resolve(self) -> tuple[str, str] | None:
+        if not self.is_installed():
+            return None
+        api_key = self._api_key()
+        if not api_key:
+            logger.info("claude_code: installed but no auth found — run `claude` to log in or set ANTHROPIC_API_KEY")
+            return None
+        model = self._model()
+        logger.info("claude_code: auto-configuring model={} via {}", model, self._auth_method())
+        return model, api_key
+
+    def status(self) -> dict:
+        installed = self.is_installed()
+        method = self._auth_method() if installed else None
+        oauth = self._oauth() if (installed and method == "subscription") else {}
+        return {
+            "installed": installed,
+            "authenticated": bool(method),
+            "auth_method": method,                          # api_key | auth_token | subscription | None
+            "subscription_type": oauth.get("subscriptionType"),
+            "token_expired": self._oauth_expired(oauth) if oauth else False,
+            "model": self._model() if installed else None,
+            "config_path": str(_SETTINGS_PATH) if _SETTINGS_PATH.exists() else None,
+            "hint": "Run `claude` to log in, or set ANTHROPIC_API_KEY in .env",
+        }
+
+    # ── internals ────────────────────────────────────────────────────────────
+
+    def _model(self) -> str:
+        try:
+            if _SETTINGS_PATH.exists():
+                data = json.loads(_SETTINGS_PATH.read_text(encoding="utf-8"))
+                slot = data.get("model") or data.get("defaultModel") or ""
+                if slot in _MODEL_SLOTS:
+                    return _MODEL_SLOTS[slot]
+                for key, val in _MODEL_SLOTS.items():
+                    if slot.startswith(key):
+                        return val
+        except Exception:
+            pass
+        return _DEFAULT_MODEL
+
+    def _oauth(self) -> dict:
+        """Return the claudeAiOauth block from Claude Code's credential file, or {}."""
+        try:
+            if _CREDS_PATH.exists():
+                data = json.loads(_CREDS_PATH.read_text(encoding="utf-8"))
+                return data.get("claudeAiOauth", {}) or {}
+        except Exception:
+            pass
+        return {}
+
+    def _oauth_expired(self, oauth: dict) -> bool:
+        """expiresAt is epoch milliseconds; treat missing as not-expired."""
+        expires_at = oauth.get("expiresAt")
+        if not expires_at:
+            return False
+        return int(expires_at) < int(time.time() * 1000)
+
+    def _api_key(self) -> str | None:
+        if key := (os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("ANTHROPIC_AUTH_TOKEN")):
+            return key
+        return self._oauth().get("accessToken") or None
+
+    def _auth_method(self) -> str | None:
+        if os.environ.get("ANTHROPIC_API_KEY"):
+            return "api_key"
+        if os.environ.get("ANTHROPIC_AUTH_TOKEN"):
+            return "auth_token"
+        if self._oauth().get("accessToken"):
+            return "subscription"
+        return None
diff --git a/src/agent/llm/identity.py b/src/agent/llm/identity.py
new file mode 100644
index 0000000..548e94d
--- /dev/null
+++ b/src/agent/llm/identity.py
@@ -0,0 +1,31 @@
+"""Provider-specific system-prompt shaping.
+
+Some backends require the system prompt to be structured a particular way before
+they will accept a request. This module centralises that logic so every LLM call
+site (agent, summarizer, CLI ask) shapes prompts consistently.
+"""
+
+from __future__ import annotations
+
+# Anthropic subscription (OAuth) tokens only accept inference when the first system
+# block identifies the caller as Claude Code. Regular API keys do not need this.
+CLAUDE_CODE_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude."
+
+
+def is_subscription_token(api_key: str | None) -> bool:
+    """True when the key is a Claude Code subscription OAuth token (sk-ant-oat…)."""
+    return bool(api_key and api_key.startswith("sk-ant-oat"))
+
+
+def shape_system_content(prompt: str, api_key: str | None) -> str | list[dict]:
+    """Shape system-message content for the active backend.
+
+    For Claude subscription OAuth tokens, return two text blocks with the Claude Code
+    identity first (required by Anthropic). For everything else, return the plain string.
+    """
+    if is_subscription_token(api_key):
+        return [
+            {"type": "text", "text": CLAUDE_CODE_IDENTITY},
+            {"type": "text", "text": prompt},
+        ]
+    return prompt
diff --git a/src/agent/summarizer.py b/src/agent/summarizer.py
index c9cc728..2dcef1a 100644
--- a/src/agent/summarizer.py
+++ b/src/agent/summarizer.py
@@ -131,13 +131,15 @@ async def maybe_summarize(agent: Any, config: dict, session_id: str) -> bool:
     history_text = _format_for_summary(to_summarize)
     start = time.time()
     try:
+        from agent.llm import resolve_model_and_key, shape_system_content
+        model_name, api_key = resolve_model_and_key()
         llm = ChatLiteLLM(
-            model=settings.llm_model,
+            model=model_name,
             api_base=settings.llm_api_base or None,
-            api_key=settings.llm_api_key or None,
+            api_key=api_key,
         )
         response = await llm.ainvoke([
-            {"role": "system", "content": _SUMMARIZE_SYSTEM},
+            {"role": "system", "content": shape_system_content(_SUMMARIZE_SYSTEM, api_key)},
             {"role": "user",   "content": f"Summarize this investigation:\n\n{history_text}"},
         ])
         summary_text = str(response.content)
diff --git a/src/api/app.py b/src/api/app.py
index 1a3edab..8d6953d 100644
--- a/src/api/app.py
+++ b/src/api/app.py
@@ -66,9 +66,9 @@ def start_event_consumer(app_instance: "FastAPI | None" = None) -> None:
     existing: asyncio.Task | None = getattr(target, "_consumer_task", None)
     if existing and not existing.done():
         return
-    from agent.event_consumer import event_consumer_loop
+    from providers import get_active_provider
 
-    target._consumer_task = asyncio.create_task(event_consumer_loop())  # type: ignore[attr-defined]
+    target._consumer_task = asyncio.create_task(get_active_provider().event_consumer_loop())  # type: ignore[attr-defined]
     logger.info("Event consumer task started")
 
 
@@ -109,9 +109,9 @@ async def lifespan(_app: FastAPI):
                 "or postgres for durable incident claims"
             )
         else:
-            from agent.poller import polling_loop
+            from providers import get_active_provider
 
-            poller_task = asyncio.create_task(polling_loop())
+            poller_task = asyncio.create_task(get_active_provider().polling_loop())
             logger.info("Proactive poller started (interval={}s)", _cfg.poll_interval_seconds)
 
     # Event consumer — started if explicitly enabled, SQS URL is set, or init wizard completed
diff --git a/src/api/routers/chat.py b/src/api/routers/chat.py
index 769246b..f07e9bc 100644
--- a/src/api/routers/chat.py
+++ b/src/api/routers/chat.py
@@ -14,7 +14,7 @@
 from loguru import logger
 
 from config import settings
-from agent.core import get_agent
+from agent.core import get_agent, get_active_model
 from agent.summarizer import maybe_summarize
 from agent.turns import calc_cost, save_turn, notify_slack
 from models.chat import ChatRequest
@@ -223,9 +223,10 @@ def _flush_text_buf():
 
     _flush_text_buf()
 
+    active_model = get_active_model()
     usage: dict[str, Any] = {
         "latency_ms": int((time.time() - start) * 1000),
-        "model": settings.llm_model,
+        "model": active_model,
         "timed_out": timed_out,
     }
     if usage_meta:
diff --git a/src/api/routers/init.py b/src/api/routers/init.py
index 3d732c4..3255512 100644
--- a/src/api/routers/init.py
+++ b/src/api/routers/init.py
@@ -13,6 +13,7 @@
 from pydantic import BaseModel, EmailStr, Field
 
 from agent.db import db
+from agent.llm import get_backend_info
 from agent.init_store import (
     get_runtime_aws_region,
     get_runtime_sqs_queue_url,
@@ -62,6 +63,7 @@ async def status():
     data["event_infra_enabled"] = bool(get_runtime_sqs_queue_url()) and bool(
         settings.sqs_queue_url or data.get("event_infra_enabled")
     )
+    data["llm_backend"] = get_backend_info()
     return data
 
 
@@ -124,11 +126,12 @@ async def setup(
 async def check_permissions_endpoint(
     _: Annotated[dict | None, Depends(require_admin)],
 ):
-    from agent.permission_checker import check_permissions as _check
+    from providers import get_active_provider
 
+    provider = get_active_provider()
     data = await load_init_async()
     results = await asyncio.get_event_loop().run_in_executor(
-        None, _check, data.get("aws_region")
+        None, provider.check_permissions, data.get("aws_region")
     )
     data["permissions"] = {svc: r["passed"] for svc, r in results.items()}
     await save_init_async(data)
@@ -162,7 +165,7 @@ async def complete(
     region = data.get("aws_region") or settings.aws_region
 
     try:
-        from agent.event_infra import setup_event_infra
+        from providers.aws.event_infra import setup_event_infra
 
         result = await asyncio.get_event_loop().run_in_executor(None, setup_event_infra, region)
         data["sqs_queue_url"] = result["queue_url"]
@@ -237,7 +240,7 @@ async def teardown_infra(
         return {"torn_down": True, "warnings": ["No event infrastructure was configured"]}
 
     try:
-        from agent.event_infra import teardown_event_infra
+        from providers.aws.event_infra import teardown_event_infra
 
         result = await asyncio.get_event_loop().run_in_executor(
             None,
diff --git a/src/api/routers/settings.py b/src/api/routers/settings.py
index ec6f79e..67c85fd 100644
--- a/src/api/routers/settings.py
+++ b/src/api/routers/settings.py
@@ -8,6 +8,7 @@
 
 from fastapi import APIRouter, Depends
 
+from agent.llm import get_backend_info
 from agent.init_store import get_runtime_aws_region
 from api.auth import get_current_user
 from config import settings
@@ -56,4 +57,4 @@ async def get_settings(
         {"key": "EVENT_CONSUMER_ENABLED",        "label": "Event consumer",         "value": str(settings.event_consumer_enabled).lower(), "hint": "EventBridge→SQS incident detection"},
     ]
 
-    return {"env": env, "agent": agent}
+    return {"env": env, "agent": agent, "llm_backend": get_backend_info()}
diff --git a/src/cli/ask.py b/src/cli/ask.py
index 2f3d009..26bf24e 100644
--- a/src/cli/ask.py
+++ b/src/cli/ask.py
@@ -17,16 +17,19 @@ def ask_cmd(
     question: Annotated[str, typer.Argument(help="Freeform question about your AWS environment.")],
 ) -> None:
     """Ask a freeform question about your AWS environment."""
+    from agent.llm import resolve_model_and_key, shape_system_content
+    model_name, api_key = resolve_model_and_key()
     model = ChatLiteLLM(
-        model=settings.llm_model,
+        model=model_name,
         api_base=settings.llm_api_base or None,
-        api_key=settings.llm_api_key or None,
+        api_key=api_key,
     )
 
     messages = [
-        SystemMessage(content=(
+        SystemMessage(content=shape_system_content(
             "You are an expert AWS SRE. Answer concisely. If you need specific AWS data to answer "
-            "accurately, say so — don't make up metrics or resource names."
+            "accurately, say so — don't make up metrics or resource names.",
+            api_key,
         )),
         HumanMessage(content=question),
     ]
diff --git a/src/cli/report.py b/src/cli/report.py
index 31dc203..7a0c5c9 100644
--- a/src/cli/report.py
+++ b/src/cli/report.py
@@ -6,7 +6,7 @@
 from rich.progress import Progress, SpinnerColumn, TextColumn
 from rich.table import Table
 
-from tools.cloudwatch import get_alarms
+from providers.aws.tools.cloudwatch import get_alarms
 
 console = Console()
 
diff --git a/src/config/appsettings.py b/src/config/appsettings.py
index 2364192..db0f4a7 100644
--- a/src/config/appsettings.py
+++ b/src/config/appsettings.py
@@ -18,6 +18,10 @@ class Settings(BaseSettings):
     openrouter_api_key: str = ""
     openrouter_base_url: str = "https://openrouter.ai/api/v1"
 
+    # Active cloud provider — selects which provider package supplies tools, context,
+    # permission checks, and event/poller loops. One active provider per deployment.
+    cloud_provider: Literal["aws", "azure", "gcp"] = "aws"
+
     aws_region: str = "us-east-1"
     aws_profile: str | None = None
 
@@ -74,5 +78,10 @@ class Settings(BaseSettings):
     # Reserved for future file-based state; init config is stored in the DB backend.
     data_dir: str = "data"
 
+    # Auto-detect Claude Code CLI and use it as the Anthropic LLM backend.
+    # Fires only when LLM_MODEL is not explicitly set and no LLM_API_KEY is present.
+    # Set to false to disable auto-detection.
+    claude_code_autodetect: bool = True
+
 
 settings = Settings()
diff --git a/src/providers/__init__.py b/src/providers/__init__.py
new file mode 100644
index 0000000..e89fc14
--- /dev/null
+++ b/src/providers/__init__.py
@@ -0,0 +1,24 @@
+"""Cloud provider registry. One active provider per deployment via CLOUD_PROVIDER."""
+
+from __future__ import annotations
+
+from config import settings
+from providers.base import CloudProvider
+
+
+def get_active_provider() -> CloudProvider:
+    """Return the provider selected by settings.cloud_provider."""
+    name = settings.cloud_provider
+    if name == "aws":
+        from providers.aws import AwsProvider
+        return AwsProvider()
+    if name == "azure":
+        from providers.azure import AzureProvider
+        return AzureProvider()
+    if name == "gcp":
+        from providers.gcp import GcpProvider
+        return GcpProvider()
+    raise ValueError(f"Unknown CLOUD_PROVIDER: {name!r} (expected aws | azure | gcp)")
+
+
+__all__ = ["CloudProvider", "get_active_provider"]
diff --git a/src/providers/aws/__init__.py b/src/providers/aws/__init__.py
new file mode 100644
index 0000000..360f067
--- /dev/null
+++ b/src/providers/aws/__init__.py
@@ -0,0 +1,47 @@
+"""AWS cloud provider — CloudWatch, CloudTrail, ECS, Lambda, EC2, RDS, IAM."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AwsProvider:
+    name = "aws"
+
+    def tools(self) -> list[Any]:
+        from providers.aws.tools.cloudtrail import ALL_CLOUDTRAIL_TOOLS
+        from providers.aws.tools.cloudwatch import ALL_CLOUDWATCH_TOOLS
+        from providers.aws.tools.ec2 import ALL_EC2_TOOLS
+        from providers.aws.tools.ecs import ALL_ECS_TOOLS
+        from providers.aws.tools.iam import ALL_IAM_TOOLS
+        from providers.aws.tools.lambda_ import ALL_LAMBDA_TOOLS
+        from providers.aws.tools.rds import ALL_RDS_TOOLS
+
+        return (
+            ALL_CLOUDWATCH_TOOLS
+            + ALL_CLOUDTRAIL_TOOLS
+            + ALL_ECS_TOOLS
+            + ALL_LAMBDA_TOOLS
+            + ALL_EC2_TOOLS
+            + ALL_RDS_TOOLS
+            + ALL_IAM_TOOLS
+        )
+
+    def collect_context(self, event: dict) -> dict:
+        from providers.aws.context import collect_context
+        return collect_context(event)
+
+    def check_permissions(self, region: str | None) -> dict:
+        from providers.aws.permissions import check_permissions
+        return check_permissions(region)
+
+    async def polling_loop(self) -> None:
+        from providers.aws.poller import polling_loop
+        await polling_loop()
+
+    async def event_consumer_loop(self) -> None:
+        from providers.aws.event_consumer import event_consumer_loop
+        await event_consumer_loop()
+
+
+__all__ = ["AwsProvider"]
diff --git a/src/agent/context_collectors.py b/src/providers/aws/context.py
similarity index 100%
rename from src/agent/context_collectors.py
rename to src/providers/aws/context.py
diff --git a/src/agent/event_consumer.py b/src/providers/aws/event_consumer.py
similarity index 99%
rename from src/agent/event_consumer.py
rename to src/providers/aws/event_consumer.py
index 3f42431..df4cb39 100644
--- a/src/agent/event_consumer.py
+++ b/src/providers/aws/event_consumer.py
@@ -249,7 +249,7 @@ async def _process_event(event: dict) -> ProcessResult:
 
     # Enrich prompt with deterministic boto3 context (no LLM cost)
     try:
-        from agent.context_collectors import collect_context
+        from providers.aws.context import collect_context
 
         context = collect_context(event)
         if context and not context.get("error"):
diff --git a/src/agent/event_infra.py b/src/providers/aws/event_infra.py
similarity index 100%
rename from src/agent/event_infra.py
rename to src/providers/aws/event_infra.py
diff --git a/src/agent/permission_checker.py b/src/providers/aws/permissions.py
similarity index 100%
rename from src/agent/permission_checker.py
rename to src/providers/aws/permissions.py
diff --git a/src/agent/poller.py b/src/providers/aws/poller.py
similarity index 98%
rename from src/agent/poller.py
rename to src/providers/aws/poller.py
index 3805265..f2743f4 100644
--- a/src/agent/poller.py
+++ b/src/providers/aws/poller.py
@@ -109,7 +109,7 @@ async def _check_alarms() -> None:
         is_recent_alert,
         release_incident,
     )
-    from tools.cloudwatch import get_alarms
+    from providers.aws.tools.cloudwatch import get_alarms
 
     data = await asyncio.get_event_loop().run_in_executor(_POLLER_POOL, get_alarms, "ALARM")
     alarms = data.get("alarms", [])
@@ -183,7 +183,7 @@ async def _check_lambda_errors() -> None:
         is_incident_claimed,
         release_incident,
     )
-    from tools.lambda_ import get_lambda_error_rate, list_lambda_functions
+    from providers.aws.tools.lambda_ import get_lambda_error_rate, list_lambda_functions
 
     funcs = await asyncio.get_event_loop().run_in_executor(_POLLER_POOL, list_lambda_functions)
     fn_list = funcs.get("functions", [])[:20]
@@ -205,7 +205,7 @@ async def _check_lambda_errors() -> None:
             continue
 
         # The aggregate alarm covers all Lambda errors — if it fired recently, skip.
-        from agent.event_infra import ALARM_NAME
+        from providers.aws.event_infra import ALARM_NAME
         aggregate_key = alarm_incident_key(ALARM_NAME)
         aggregate_window = max(3, (settings.investigation_timeout // 60) + 2)
         if await is_incident_claimed(aggregate_key, aggregate_window):
diff --git a/src/providers/aws/tools/__init__.py b/src/providers/aws/tools/__init__.py
new file mode 100644
index 0000000..45b3145
--- /dev/null
+++ b/src/providers/aws/tools/__init__.py
@@ -0,0 +1 @@
+"""AWS boto3-backed agent tools."""
diff --git a/src/tools/cloudtrail.py b/src/providers/aws/tools/cloudtrail.py
similarity index 100%
rename from src/tools/cloudtrail.py
rename to src/providers/aws/tools/cloudtrail.py
diff --git a/src/tools/cloudwatch.py b/src/providers/aws/tools/cloudwatch.py
similarity index 100%
rename from src/tools/cloudwatch.py
rename to src/providers/aws/tools/cloudwatch.py
diff --git a/src/tools/ec2.py b/src/providers/aws/tools/ec2.py
similarity index 100%
rename from src/tools/ec2.py
rename to src/providers/aws/tools/ec2.py
diff --git a/src/tools/ecs.py b/src/providers/aws/tools/ecs.py
similarity index 100%
rename from src/tools/ecs.py
rename to src/providers/aws/tools/ecs.py
diff --git a/src/tools/iam.py b/src/providers/aws/tools/iam.py
similarity index 100%
rename from src/tools/iam.py
rename to src/providers/aws/tools/iam.py
diff --git a/src/tools/lambda_.py b/src/providers/aws/tools/lambda_.py
similarity index 100%
rename from src/tools/lambda_.py
rename to src/providers/aws/tools/lambda_.py
diff --git a/src/tools/rds.py b/src/providers/aws/tools/rds.py
similarity index 100%
rename from src/tools/rds.py
rename to src/providers/aws/tools/rds.py
diff --git a/src/providers/azure/__init__.py b/src/providers/azure/__init__.py
new file mode 100644
index 0000000..191a7ac
--- /dev/null
+++ b/src/providers/azure/__init__.py
@@ -0,0 +1,35 @@
+"""Azure cloud provider — stub. Not yet implemented.
+
+To implement: add tools under providers/azure/tools/ (Azure Monitor, App Insights,
+Functions, VMs…), a context collector, permission checks, and event ingestion
+(Event Grid / Service Bus), then fill in the methods below.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+
+
+class AzureProvider:
+    name = "azure"
+
+    def tools(self) -> list[Any]:
+        logger.warning("Azure provider not yet implemented — no cloud tools loaded")
+        return []
+
+    def collect_context(self, event: dict) -> dict:
+        return {}
+
+    def check_permissions(self, region: str | None) -> dict:
+        return {}
+
+    async def polling_loop(self) -> None:
+        return
+
+    async def event_consumer_loop(self) -> None:
+        return
+
+
+__all__ = ["AzureProvider"]
diff --git a/src/providers/base.py b/src/providers/base.py
new file mode 100644
index 0000000..85eb95d
--- /dev/null
+++ b/src/providers/base.py
@@ -0,0 +1,36 @@
+"""CloudProvider protocol — one implementation per cloud (AWS, Azure, GCP).
+
+A provider bundles everything cloud-specific: the agent tools, deterministic context
+collection, permission checks, and the proactive poller / event-consumer loops. The
+agent core (LangGraph, LLM, skills, prompts) stays cloud-agnostic and talks only to
+the active provider, selected by the CLOUD_PROVIDER setting.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class CloudProvider(Protocol):
+    name: str  # "aws" | "azure" | "gcp"
+
+    def tools(self) -> list[Any]:
+        """Provider-specific agent tools (boto3 / SDK-backed)."""
+        ...
+
+    def collect_context(self, event: dict) -> dict:
+        """Deterministically pre-fetch resource facts before the LLM runs."""
+        ...
+
+    def check_permissions(self, region: str | None) -> dict:
+        """Verify credentials have the required read permissions, per service."""
+        ...
+
+    async def polling_loop(self) -> None:
+        """Proactive anomaly-detection loop (no-op if unsupported)."""
+        ...
+
+    async def event_consumer_loop(self) -> None:
+        """Event-driven incident-detection loop (no-op if unsupported)."""
+        ...
diff --git a/src/providers/gcp/__init__.py b/src/providers/gcp/__init__.py
new file mode 100644
index 0000000..d1f621c
--- /dev/null
+++ b/src/providers/gcp/__init__.py
@@ -0,0 +1,35 @@
+"""GCP cloud provider — stub. Not yet implemented.
+
+To implement: add tools under providers/gcp/tools/ (Cloud Logging, Cloud Monitoring,
+Cloud Functions, GCE…), a context collector, permission checks, and event ingestion
+(Cloud Pub/Sub), then fill in the methods below.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+
+
+class GcpProvider:
+    name = "gcp"
+
+    def tools(self) -> list[Any]:
+        logger.warning("GCP provider not yet implemented — no cloud tools loaded")
+        return []
+
+    def collect_context(self, event: dict) -> dict:
+        return {}
+
+    def check_permissions(self, region: str | None) -> dict:
+        return {}
+
+    async def polling_loop(self) -> None:
+        return
+
+    async def event_consumer_loop(self) -> None:
+        return
+
+
+__all__ = ["GcpProvider"]
diff --git a/tests/integration/test_dlq_logic.py b/tests/integration/test_dlq_logic.py
index c72bb37..87aacdd 100644
--- a/tests/integration/test_dlq_logic.py
+++ b/tests/integration/test_dlq_logic.py
@@ -89,7 +89,7 @@ def test_processing_exception_leaves_message_in_queue():
 
 def test_max_receive_count_constant():
     """MAX_RECEIVE_COUNT must match what we verified in AWS."""
-    from agent.event_infra import MAX_RECEIVE_COUNT
+    from providers.aws.event_infra import MAX_RECEIVE_COUNT
     assert MAX_RECEIVE_COUNT == "5", (
         "maxReceiveCount changed — update the DLQ in AWS to match "
         "(aws sqs set-queue-attributes --attribute-names RedrivePolicy)"
@@ -97,7 +97,7 @@ def test_max_receive_count_constant():
 
 
 def test_dlq_queue_name_constant():
-    from agent.event_infra import DLQ_QUEUE_NAME, QUEUE_NAME
+    from providers.aws.event_infra import DLQ_QUEUE_NAME, QUEUE_NAME
     assert DLQ_QUEUE_NAME == f"{QUEUE_NAME}-dlq", (
         "DLQ name must be the main queue name with '-dlq' suffix"
     )
@@ -132,12 +132,12 @@ def fake_delete(QueueUrl, ReceiptHandle):  # noqa: N803
     mock_sqs.delete_message.side_effect = fake_delete
 
     with (
-        patch("agent.event_consumer.get_runtime_sqs_queue_url", return_value="https://fake-url"),
-        patch("agent.event_consumer.get_runtime_aws_region", return_value="us-east-1"),
+        patch("providers.aws.event_consumer.get_runtime_sqs_queue_url", return_value="https://fake-url"),
+        patch("providers.aws.event_consumer.get_runtime_aws_region", return_value="us-east-1"),
         patch("boto3.Session") as mock_session,
     ):
         mock_session.return_value.client.return_value = mock_sqs
-        from agent.event_consumer import event_consumer_loop
+        from providers.aws.event_consumer import event_consumer_loop
         try:
             await event_consumer_loop()
         except asyncio.CancelledError:
@@ -180,13 +180,13 @@ async def fake_process_event(_event):
     mock_sqs.delete_message.side_effect = fake_delete
 
     with (
-        patch("agent.event_consumer.get_runtime_sqs_queue_url", return_value="https://fake-url"),
-        patch("agent.event_consumer.get_runtime_aws_region", return_value="us-east-1"),
-        patch("agent.event_consumer._process_event", side_effect=fake_process_event),
+        patch("providers.aws.event_consumer.get_runtime_sqs_queue_url", return_value="https://fake-url"),
+        patch("providers.aws.event_consumer.get_runtime_aws_region", return_value="us-east-1"),
+        patch("providers.aws.event_consumer._process_event", side_effect=fake_process_event),
         patch("boto3.Session") as mock_session,
     ):
         mock_session.return_value.client.return_value = mock_sqs
-        from agent.event_consumer import event_consumer_loop
+        from providers.aws.event_consumer import event_consumer_loop
         try:
             await event_consumer_loop()
         except asyncio.CancelledError:
diff --git a/tests/integration/test_poller.py b/tests/integration/test_poller.py
index 67a3218..77714d8 100644
--- a/tests/integration/test_poller.py
+++ b/tests/integration/test_poller.py
@@ -4,7 +4,7 @@
 
 import asyncio
 
-from agent import poller
+from providers.aws import poller
 from agent.incident_keys import alarm_incident_key, lambda_metric_incident_key
 
 
@@ -64,7 +64,7 @@ async def fake_complete(_key, _status="completed", _session_id=None):
     async def fake_release(_key):
         raise AssertionError("successful poller investigation should not release the claim")
 
-    monkeypatch.setattr("tools.cloudwatch.get_alarms", fake_get_alarms)
+    monkeypatch.setattr("providers.aws.tools.cloudwatch.get_alarms", fake_get_alarms)
     monkeypatch.setattr("agent.monitor_store.is_recent_alert", fake_recent)
     monkeypatch.setattr("agent.monitor_store.claim_incident", fake_claim)
     monkeypatch.setattr("agent.monitor_store.complete_incident", fake_complete)
@@ -123,8 +123,8 @@ async def fake_release(_key):
     async def fake_is_claimed(_key, _within_minutes=3):
         return False
 
-    monkeypatch.setattr("tools.lambda_.list_lambda_functions", fake_list_lambda_functions)
-    monkeypatch.setattr("tools.lambda_.get_lambda_error_rate", fake_get_lambda_error_rate)
+    monkeypatch.setattr("providers.aws.tools.lambda_.list_lambda_functions", fake_list_lambda_functions)
+    monkeypatch.setattr("providers.aws.tools.lambda_.get_lambda_error_rate", fake_get_lambda_error_rate)
     monkeypatch.setattr("agent.monitor_store.claim_incident", fake_claim)
     monkeypatch.setattr("agent.monitor_store.complete_incident", fake_complete)
     monkeypatch.setattr("agent.monitor_store.release_incident", fake_release)
diff --git a/tests/test_tools/test_cloudwatch.py b/tests/test_tools/test_cloudwatch.py
index 2c0ba16..ad972b1 100644
--- a/tests/test_tools/test_cloudwatch.py
+++ b/tests/test_tools/test_cloudwatch.py
@@ -1,7 +1,7 @@
 import boto3
 from moto import mock_aws
 
-from tools.cloudwatch import (
+from providers.aws.tools.cloudwatch import (
     describe_log_groups,
     get_alarm_history,
     get_alarms,
diff --git a/tests/test_tools/test_ecs.py b/tests/test_tools/test_ecs.py
index 41ea9a0..e9664b4 100644
--- a/tests/test_tools/test_ecs.py
+++ b/tests/test_tools/test_ecs.py
@@ -1,7 +1,7 @@
 import boto3
 from moto import mock_aws
 
-from tools.ecs import describe_ecs_service, list_ecs_clusters, list_ecs_services
+from providers.aws.tools.ecs import describe_ecs_service, list_ecs_clusters, list_ecs_services
 
 
 @mock_aws
diff --git a/tests/test_tools/test_lambda.py b/tests/test_tools/test_lambda.py
index 7fced2c..8d854fb 100644
--- a/tests/test_tools/test_lambda.py
+++ b/tests/test_tools/test_lambda.py
@@ -1,7 +1,7 @@
 import boto3
 from moto import mock_aws
 
-from tools.lambda_ import get_lambda_error_rate, get_lambda_function_config, list_lambda_functions
+from providers.aws.tools.lambda_ import get_lambda_error_rate, get_lambda_function_config, list_lambda_functions
 
 
 def _create_lambda_role(iam_client: boto3.client) -> str:
diff --git a/tests/test_tools/test_rds.py b/tests/test_tools/test_rds.py
index d5b93ab..2f05281 100644
--- a/tests/test_tools/test_rds.py
+++ b/tests/test_tools/test_rds.py
@@ -1,7 +1,7 @@
 import boto3
 from moto import mock_aws
 
-from tools.rds import describe_rds_instances, get_rds_events
+from providers.aws.tools.rds import describe_rds_instances, get_rds_events
 
 
 @mock_aws

From 491993538ffa76e5d35133b622b77996d249d3b8 Mon Sep 17 00:00:00 2001
From: AhmadHammad21 <ahmedhammad8765@gmail.com>
Date: Fri, 22 May 2026 16:14:47 +0300
Subject: [PATCH 2/3] docs(llm): clarify that Claude Code requires
 LLM_MODEL/OPENROUTER_API_KEY unset

Auto-detection only activates when no other provider is explicitly configured.
Restructure .env.example to present Claude Code as the zero-config default.
---
 .env.example          | 23 +++++++++++++----------
 docs/llm_providers.md | 28 ++++++++++++++++++----------
 2 files changed, 31 insertions(+), 20 deletions(-)

diff --git a/.env.example b/.env.example
index 8914953..c039120 100644
--- a/.env.example
+++ b/.env.example
@@ -1,15 +1,18 @@
-# LLM — use LiteLLM model string format (provider/model)
-# OpenRouter (default — 200+ models via one key)
-LLM_MODEL=openrouter/openai/gpt-4o
-OPENROUTER_API_KEY=sk-or-...
-
-# Claude Code auto-detection (default: true)
-# When enabled and LLM_MODEL/API keys are not explicitly set, the app will detect
-# the Claude Code CLI (~/.claude/) and use it as the Anthropic LLM backend automatically.
-# Set to false to disable.
+# ─── LLM provider ─────────────────────────────────────────────────────────────
+# Pick ONE option. Uses LiteLLM model string format (provider/model).
+#
+# Option A — Claude Code (zero-config): if the `claude` CLI is installed and logged
+# in, it is auto-detected and your subscription is used as the LLM. For this to work,
+# leave LLM_MODEL, OPENROUTER_API_KEY, ANTHROPIC_API_KEY and LLM_API_BASE UNSET below.
+# Set CLAUDE_CODE_AUTODETECT=false to turn detection off.
 # CLAUDE_CODE_AUTODETECT=true
 
-# Anthropic direct
+# Option B — OpenRouter (200+ models via one key). Uncomment both lines to use it
+# (this takes priority over Claude Code auto-detection).
+# LLM_MODEL=openrouter/openai/gpt-4o
+# OPENROUTER_API_KEY=sk-or-...
+
+# Anthropic direct (API key, not subscription)
 # LLM_MODEL=anthropic/claude-3-5-sonnet-20241022
 # ANTHROPIC_API_KEY=sk-ant-...
 
diff --git a/docs/llm_providers.md b/docs/llm_providers.md
index 8b57f18..0a504e0 100644
--- a/docs/llm_providers.md
+++ b/docs/llm_providers.md
@@ -22,21 +22,29 @@ LiteLLM routes to Anthropic API  →  same agent graph, same tools
 
 ## Supported providers (examples)
 
-### Claude Code (zero-config, auto-detected)
+### Claude Code (zero-config, uses your subscription)
 
-If you have [Claude Code](https://claude.ai/code) installed and authenticated, OpenDevOps detects it automatically — no `.env` changes required.
+If you have [Claude Code](https://claude.ai/code) installed and logged in, OpenDevOps can use your **existing Claude subscription** as the LLM — no API key, no `.env` changes.
+
+> **Important — leave these unset.** Auto-detection only activates when you have **not** explicitly configured another provider. To use Claude Code, make sure your `.env` does **not** set any of:
+> - `LLM_MODEL`
+> - `OPENROUTER_API_KEY`
+> - `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`
+> - `LLM_API_BASE`
+>
+> If any of those are present, that provider wins and Claude Code is skipped. The simplest setup is an empty (or absent) `.env` — Claude Code is picked up automatically.
 
 **How it works:**
-1. On startup, the app checks if the `claude` CLI is in your PATH
-2. It reads `~/.claude/settings.json` for your configured model slot
-3. It picks up your auth from `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or Claude Code's OAuth credential file
+1. On startup the app checks whether the `claude` CLI is in your `PATH`.
+2. It reads `~/.claude/settings.json` for your selected model (e.g. `sonnet` → `anthropic/claude-sonnet-4-6`).
+3. It reuses Claude Code's subscription login — the OAuth token in `~/.claude/.credentials.json` (`sk-ant-oat…`). LiteLLM sends it as a Bearer token with the OAuth beta header automatically.
 
-The active LLM backend is shown in **Settings → Environment** and in the **setup wizard**.
+The active backend is shown in **Settings → Environment** and in the **setup wizard**.
 
-To disable auto-detection:
-```bash
-CLAUDE_CODE_AUTODETECT=false
-```
+**Notes:**
+- Rate limits are shared with your interactive Claude Code usage — both draw from the same subscription quota.
+- The OAuth token expires periodically; running any `claude` command refreshes it.
+- To force a different provider even when Claude Code is installed, set `LLM_MODEL` + the matching key, or disable detection entirely with `CLAUDE_CODE_AUTODETECT=false`.
 
 ---
 

From 2a37bbff7f53340e70a90410b4e364f622e22394 Mon Sep 17 00:00:00 2001
From: AhmadHammad21 <ahmedhammad8765@gmail.com>
Date: Fri, 22 May 2026 23:23:39 +0300
Subject: [PATCH 3/3] test(llm): add hermetic tests for Claude Code detector
 and backend resolution
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers token detection, model-slot mapping, env-key vs subscription precedence,
expired-token flag, and the full backend resolution ladder (including the
OpenRouter-blocks-Claude-Code case). Fully mocked — no ~/.claude access, no
network, no API spend.
---
 tests/test_llm/__init__.py                  |   0
 tests/test_llm/test_backend.py              | 104 ++++++++++++++++++
 tests/test_llm/test_claude_code_detector.py | 116 ++++++++++++++++++++
 tests/test_llm/test_identity.py             |  26 +++++
 4 files changed, 246 insertions(+)
 create mode 100644 tests/test_llm/__init__.py
 create mode 100644 tests/test_llm/test_backend.py
 create mode 100644 tests/test_llm/test_claude_code_detector.py
 create mode 100644 tests/test_llm/test_identity.py

diff --git a/tests/test_llm/__init__.py b/tests/test_llm/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_llm/test_backend.py b/tests/test_llm/test_backend.py
new file mode 100644
index 0000000..848193e
--- /dev/null
+++ b/tests/test_llm/test_backend.py
@@ -0,0 +1,104 @@
+"""Backend resolution precedence — the ladder that decides which provider wins.
+
+All detectors are stubbed; no real ~/.claude access, no network, no API spend.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from agent.llm import backend
+
+
+class FakeDetector:
+    name = "claude_code"
+    label = "Claude Code"
+    provider = "anthropic"
+
+    def __init__(self, installed=True, resolved=("anthropic/claude-sonnet-4-6", "sk-ant-oat01-x")):
+        self._installed = installed
+        self._resolved = resolved
+
+    @property
+    def enabled(self):
+        return True
+
+    def is_installed(self):
+        return self._installed
+
+    def resolve(self):
+        return self._resolved
+
+    def status(self):
+        return {"model": "anthropic/claude-sonnet-4-6", "hint": "log in with claude"}
+
+
+@pytest.fixture
+def clean_env(monkeypatch):
+    """Clear provider env vars and set baseline settings (default OpenRouter model, no keys)."""
+    for var in (
+        "LLM_MODEL", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN",
+        "OPENAI_API_KEY", "GROQ_API_KEY", "COHERE_API_KEY", "MISTRAL_API_KEY",
+        "OPENROUTER_API_KEY",
+    ):
+        monkeypatch.delenv(var, raising=False)
+    monkeypatch.setattr(backend.settings, "llm_api_base", None)
+    monkeypatch.setattr(backend.settings, "llm_api_key", None)
+    monkeypatch.setattr(backend.settings, "openrouter_api_key", "")
+    monkeypatch.setattr(backend.settings, "llm_model", "openrouter/openai/gpt-4o")
+    monkeypatch.setattr(backend.settings, "claude_code_autodetect", True)
+
+
+def test_claude_code_wins_when_nothing_else_configured(monkeypatch, clean_env):
+    monkeypatch.setattr(backend, "ALL_DETECTORS", [FakeDetector()])
+    info = backend.get_backend_info()
+    assert info["source"] == "claude_code"
+    assert info["configured"] is True
+    assert info["model"] == "anthropic/claude-sonnet-4-6"
+
+
+def test_openrouter_key_blocks_claude_code(monkeypatch, clean_env):
+    # The precedence that surprised us during testing: OPENROUTER set => Claude Code skipped.
+    monkeypatch.setattr(backend.settings, "openrouter_api_key", "sk-or-xxx")
+    monkeypatch.setattr(backend, "ALL_DETECTORS", [FakeDetector()])
+    assert backend.get_backend_info()["source"] == "openrouter"
+
+
+def test_anthropic_env_key_wins(monkeypatch, clean_env):
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-api03-x")
+    monkeypatch.setattr(backend, "ALL_DETECTORS", [FakeDetector()])
+    assert backend.get_backend_info()["source"] == "anthropic"
+
+
+def test_custom_endpoint_wins(monkeypatch, clean_env):
+    monkeypatch.setattr(backend.settings, "llm_api_base", "http://localhost:11434")
+    assert backend.get_backend_info()["source"] == "custom"
+
+
+def test_explicit_model_with_openai_key(monkeypatch, clean_env):
+    monkeypatch.setenv("LLM_MODEL", "openai/gpt-4o")
+    monkeypatch.setattr(backend.settings, "llm_model", "openai/gpt-4o")
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-x")
+    monkeypatch.setattr(backend, "ALL_DETECTORS", [FakeDetector()])
+    assert backend.get_backend_info()["source"] == "openai"
+
+
+def test_installed_but_unauthenticated_detector(monkeypatch, clean_env):
+    monkeypatch.setattr(backend, "ALL_DETECTORS", [FakeDetector(installed=True, resolved=None)])
+    info = backend.get_backend_info()
+    assert info["source"] == "claude_code_no_auth"
+    assert info["configured"] is False
+
+
+def test_unconfigured_default(monkeypatch, clean_env):
+    monkeypatch.setattr(backend, "ALL_DETECTORS", [])
+    info = backend.get_backend_info()
+    assert info["source"] == "default"
+    assert info["configured"] is False
+
+
+def test_resolve_model_and_key_uses_detector(monkeypatch, clean_env):
+    monkeypatch.setattr(backend, "ALL_DETECTORS", [FakeDetector()])
+    model, key = backend.resolve_model_and_key()
+    assert model == "anthropic/claude-sonnet-4-6"
+    assert key == "sk-ant-oat01-x"
diff --git a/tests/test_llm/test_claude_code_detector.py b/tests/test_llm/test_claude_code_detector.py
new file mode 100644
index 0000000..a99d0a8
--- /dev/null
+++ b/tests/test_llm/test_claude_code_detector.py
@@ -0,0 +1,116 @@
+"""ClaudeCodeDetector — fully mocked: no real ~/.claude access, no network, no API spend."""
+
+from __future__ import annotations
+
+import json
+import time
+
+import pytest
+
+from agent.llm.detectors import claude_code
+from agent.llm.detectors.claude_code import ClaudeCodeDetector
+
+
+@pytest.fixture
+def clean_anthropic_env(monkeypatch):
+    """Remove env auth so tests are deterministic regardless of the host machine."""
+    for var in ("ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"):
+        monkeypatch.delenv(var, raising=False)
+
+
+@pytest.fixture
+def fake_claude_home(tmp_path, monkeypatch):
+    """Point the detector at temp credential/settings files instead of the real ~/.claude."""
+    settings_path = tmp_path / "settings.json"
+    creds_path = tmp_path / ".credentials.json"
+    monkeypatch.setattr(claude_code, "_SETTINGS_PATH", settings_path)
+    monkeypatch.setattr(claude_code, "_CREDS_PATH", creds_path)
+    return settings_path, creds_path
+
+
+def _write(path, data):
+    path.write_text(json.dumps(data), encoding="utf-8")
+
+
+def _installed(monkeypatch):
+    monkeypatch.setattr(claude_code.shutil, "which", lambda _name: "/usr/bin/claude")
+
+
+def test_not_installed(monkeypatch, fake_claude_home):
+    monkeypatch.setattr(claude_code.shutil, "which", lambda _name: None)
+    det = ClaudeCodeDetector()
+    assert det.is_installed() is False
+    assert det.resolve() is None
+    st = det.status()
+    assert st["installed"] is False
+    assert st["authenticated"] is False
+
+
+def test_installed_subscription_resolves(monkeypatch, fake_claude_home, clean_anthropic_env):
+    settings_path, creds_path = fake_claude_home
+    _installed(monkeypatch)
+    _write(settings_path, {"model": "sonnet"})
+    _write(creds_path, {"claudeAiOauth": {
+        "accessToken": "sk-ant-oat01-xyz",
+        "expiresAt": int(time.time() * 1000) + 3_600_000,
+        "subscriptionType": "pro",
+    }})
+    det = ClaudeCodeDetector()
+    model, key = det.resolve()
+    assert model == "anthropic/claude-sonnet-4-6"
+    assert key == "sk-ant-oat01-xyz"
+    st = det.status()
+    assert st["auth_method"] == "subscription"
+    assert st["subscription_type"] == "pro"
+    assert st["token_expired"] is False
+
+
+@pytest.mark.parametrize("slot,expected", [
+    ("sonnet", "anthropic/claude-sonnet-4-6"),
+    ("opus", "anthropic/claude-opus-4-7"),
+    ("haiku", "anthropic/claude-haiku-4-5-20251001"),
+    ("some-future-model", "anthropic/claude-sonnet-4-6"),  # unknown slot → default
+])
+def test_model_slot_mapping(monkeypatch, fake_claude_home, clean_anthropic_env, slot, expected):
+    settings_path, creds_path = fake_claude_home
+    _installed(monkeypatch)
+    _write(settings_path, {"model": slot})
+    _write(creds_path, {"claudeAiOauth": {"accessToken": "sk-ant-oat01-xyz"}})
+    assert ClaudeCodeDetector().resolve()[0] == expected
+
+
+def test_env_key_takes_precedence_over_subscription(monkeypatch, fake_claude_home):
+    settings_path, creds_path = fake_claude_home
+    _installed(monkeypatch)
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-api03-realkey")
+    monkeypatch.delenv("ANTHROPIC_AUTH_TOKEN", raising=False)
+    _write(settings_path, {"model": "sonnet"})
+    _write(creds_path, {"claudeAiOauth": {"accessToken": "sk-ant-oat01-xyz"}})
+    det = ClaudeCodeDetector()
+    _model, key = det.resolve()
+    assert key == "sk-ant-api03-realkey"
+    assert det.status()["auth_method"] == "api_key"
+
+
+def test_installed_but_no_auth(monkeypatch, fake_claude_home, clean_anthropic_env):
+    settings_path, _creds_path = fake_claude_home
+    _installed(monkeypatch)
+    _write(settings_path, {"model": "sonnet"})  # no creds file, no env
+    det = ClaudeCodeDetector()
+    assert det.resolve() is None
+    st = det.status()
+    assert st["installed"] is True
+    assert st["authenticated"] is False
+    assert st["auth_method"] is None
+
+
+def test_expired_token_flag(monkeypatch, fake_claude_home, clean_anthropic_env):
+    settings_path, creds_path = fake_claude_home
+    _installed(monkeypatch)
+    _write(settings_path, {"model": "sonnet"})
+    _write(creds_path, {"claudeAiOauth": {
+        "accessToken": "sk-ant-oat01-xyz",
+        "expiresAt": int(time.time() * 1000) - 1000,  # already expired
+        "subscriptionType": "pro",
+    }})
+    assert ClaudeCodeDetector().status()["token_expired"] is True
diff --git a/tests/test_llm/test_identity.py b/tests/test_llm/test_identity.py
new file mode 100644
index 0000000..6132ea5
--- /dev/null
+++ b/tests/test_llm/test_identity.py
@@ -0,0 +1,26 @@
+"""System-prompt shaping for subscription OAuth tokens."""
+
+from __future__ import annotations
+
+from agent.llm.identity import CLAUDE_CODE_IDENTITY, is_subscription_token, shape_system_content
+
+
+def test_is_subscription_token():
+    assert is_subscription_token("sk-ant-oat01-abc") is True
+    assert is_subscription_token("sk-ant-api03-abc") is False
+    assert is_subscription_token("sk-or-xxx") is False
+    assert is_subscription_token(None) is False
+    assert is_subscription_token("") is False
+
+
+def test_shape_system_content_subscription_returns_two_blocks():
+    out = shape_system_content("DEVOPS PROMPT", "sk-ant-oat01-abc")
+    assert isinstance(out, list)
+    assert out[0] == {"type": "text", "text": CLAUDE_CODE_IDENTITY}
+    assert out[1] == {"type": "text", "text": "DEVOPS PROMPT"}
+
+
+def test_shape_system_content_plain_returns_string():
+    assert shape_system_content("P", "sk-or-xxx") == "P"
+    assert shape_system_content("P", None) == "P"
+    assert shape_system_content("P", "sk-ant-api03-key") == "P"