shadowcat 2.0.0__py3-none-any.whl

agent/core/backend.py

@@ -0,0 +1,1667 @@
+"""Framework-agnostic agent backend protocol and implementations."""
+
+import asyncio
+import json
+import os
+import shlex
+import time
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from agent.core.profiling import mark, span
+from agent.core.sanitizer import scrubbed_env, wrap_untrusted
+
+
+class MessageType(Enum):
+    """Framework-agnostic message types from agent backends."""
+
+    TEXT = "text"
+    TOOL_START = "tool_start"
+    TOOL_RESULT = "tool_result"
+    RESULT = "result"
+    ERROR = "error"
+
+
+@dataclass
+class AgentMessage:
+    """Framework-agnostic message from any agent backend."""
+
+    type: MessageType
+    content: Any
+    tool_name: str | None = None
+    tool_args: dict[str, Any] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class AgentBackend(ABC):
+    """
+    Abstract interface for agent backends.
+
+    Implement this to support different LLM providers:
+    - OpenRouterBackend (current — OpenAI-compatible Chat Completions via OpenRouter)
+    - Any future provider that speaks the OpenAI protocol
+    """
+
+    @abstractmethod
+    async def connect(self) -> None:
+        """Establish connection to the agent."""
+        ...
+
+    @abstractmethod
+    async def disconnect(self) -> None:
+        """Close connection."""
+        ...
+
+    @abstractmethod
+    async def query(self, prompt: str) -> None:
+        """Send a query/instruction to the agent."""
+        ...
+
+    @abstractmethod
+    def receive_messages(self) -> AsyncIterator[AgentMessage]:
+        """Async iterator yielding messages from agent."""
+        ...
+
+    @property
+    @abstractmethod
+    def session_id(self) -> str | None:
+        """Current session ID (if backend supports sessions)."""
+        ...
+
+    @property
+    def supports_resume(self) -> bool:
+        """Whether this backend supports session resume."""
+        return False
+
+    @abstractmethod
+    async def resume(self, session_id: str) -> bool:
+        """Resume a previous session. Returns success."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas (OpenAI function-calling format)
+# ---------------------------------------------------------------------------
+
+_TOOLS: list[dict[str, Any]] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "bash",
+            "description": (
+                "Execute a bash command in the working directory. "
+                "Use this for network enumeration, exploitation, running scripts, "
+                "reading output of security tools (nmap, curl, python, etc.)."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "The bash command to execute.",
+                    }
+                },
+                "required": ["command"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read the contents of a file.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path to the file (absolute, or relative to working directory).",
+                    }
+                },
+                "required": ["path"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Write content to a file, creating parent directories as needed.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Destination path.",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "Text content to write.",
+                    },
+                },
+                "required": ["path", "content"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "http_request",
+            "description": (
+                "Send an HTTP request through a persistent session. Cookies, "
+                "auth headers, and CSRF tokens carry over between calls "
+                "automatically — use this instead of curl/wget for any web "
+                "request. HTML responses are distilled (scripts/styles/SVG "
+                "stripped; forms, links, comments, meta, headings preserved) "
+                "to keep token usage low. Returns structured JSON with status, "
+                "filtered headers, distilled body, cookies set, elapsed_ms, "
+                "and the redirect chain."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "method": {
+                        "type": "string",
+                        "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+                    },
+                    "url": {"type": "string", "description": "Absolute URL."},
+                    "headers": {
+                        "type": "object",
+                        "additionalProperties": {"type": "string"},
+                        "description": "Extra request headers. Persistent session "
+                        "headers (cookies, prior Authorization) are sent automatically.",
+                    },
+                    "body": {
+                        "type": "string",
+                        "description": "Raw request body. Mutually exclusive with form/json_body.",
+                    },
+                    "form": {
+                        "type": "object",
+                        "description": "Form-encoded fields. Sets Content-Type to "
+                        "application/x-www-form-urlencoded.",
+                    },
+                    "json_body": {
+                        "type": "object",
+                        "description": "JSON body. Sets Content-Type to application/json.",
+                    },
+                    "follow_redirects": {"type": "boolean", "default": True},
+                    "auto_csrf": {
+                        "type": "boolean",
+                        "default": True,
+                        "description": "Inject a CSRF token previously seen for this "
+                        "form action if the request doesn't already carry one.",
+                    },
+                    "timeout_seconds": {"type": "number", "default": 30},
+                },
+                "required": ["method", "url"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "hash_crack",
+            "description": "Crack a hash using hashcat/rockyou under the hood.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "hash_value": {
+                        "type": "string",
+                        "description": "The hash string to crack.",
+                    }
+                },
+                "required": ["hash_value"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "decode_chain",
+            "description": "Recursively decode base64/hex/url encoding.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "encoded_string": {
+                        "type": "string",
+                        "description": "The encoded string to decode.",
+                    }
+                },
+                "required": ["encoded_string"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "sqli_probe",
+            "description": "Probe a URL for SQL injection using sqlmap.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "url": {
+                        "type": "string",
+                        "description": "The target URL to probe.",
+                    }
+                },
+                "required": ["url"],
+            },
+        },
+    },
+]
+
+_TOOL_TIMEOUT_SECONDS = 120
+_OUTPUT_TRUNCATE_CHARS = 12_000
+
+# Hard ceiling on tool-call turns within one `receive_messages` call. Without
+# this, a model stuck in a degenerate "call → fail → call again" loop can
+# burn budget indefinitely under the LLM-timeout backstop.
+_MAX_AGENT_TURNS = 60
+
+# Hard ceiling on a single LLM round-trip (model call). Applied at two layers:
+#   1. The SDK's own httpx timeout (`AsyncOpenAI(timeout=...)`)
+#   2. An `asyncio.wait_for` wrapping the create() call.
+# Two layers because (1) catches socket-level stalls but can be defeated by a
+# server that streams keepalive bytes forever; (2) is the unconditional ceiling.
+# The wait_for budget is slightly larger so the SDK's own timeout fires first
+# and surfaces a clean httpx.TimeoutException rather than a CancelledError.
+_LLM_REQUEST_TIMEOUT_SECONDS = 180
+_LLM_WAITFOR_TIMEOUT_SECONDS = 210
+
+
+# ---------------------------------------------------------------------------
+# Prompt caching helpers
+# ---------------------------------------------------------------------------
+#
+# The system prompt (the large CTF methodology) and the tool schemas are
+# byte-identical on every one of the up-to-_MAX_AGENT_TURNS calls in a session.
+# Flagging that stable prefix with Anthropic's `cache_control: ephemeral` turns
+# it into a cache read (~10% of input price) after the first turn — the single
+# biggest cost lever for a multi-turn agent. Native Claude supports this
+# directly; OpenRouter forwards the field to Anthropic/Gemini upstreams. Other
+# providers are left untouched (they auto-cache a byte-stable prefix anyway).
+
+_CACHE_CONTROL_EPHEMERAL: dict[str, str] = {"type": "ephemeral"}
+
+
+def _is_anthropic_model(model: str) -> bool:
+    """True for Claude models (native names or OpenRouter's `anthropic/` slug)."""
+    m = (model or "").lower()
+    return "claude" in m or "anthropic" in m
+
+
+def _cacheable_system_message(system_prompt: str) -> dict[str, Any]:
+    """OpenAI-format system message with its text part flagged for caching."""
+    return {
+        "role": "system",
+        "content": [
+            {
+                "type": "text",
+                "text": system_prompt,
+                "cache_control": _CACHE_CONTROL_EPHEMERAL,
+            }
+        ],
+    }
+
+
+def _build_cached_tools(tools: list[dict[str, Any]], model: str) -> list[dict[str, Any]]:
+    """Copy ``tools`` with a cache breakpoint on the last entry for Claude models.
+
+    Never mutates the shared ``_TOOLS`` global. Non-Anthropic models get the
+    list back unchanged (they reject or ignore the field).
+    """
+    if not tools or not _is_anthropic_model(model):
+        return tools
+    cached = list(tools)
+    cached[-1] = {**cached[-1], "cache_control": _CACHE_CONTROL_EPHEMERAL}
+    return cached
+
+
+_GLOBAL_HTTP_CLIENT = None
+_GLOBAL_CSRF_JAR: dict[str, str] = {}
+
+
+def get_shared_http_client() -> Any:
+    """Get or create the shared HTTP client for the event loop."""
+    global _GLOBAL_HTTP_CLIENT
+    if _GLOBAL_HTTP_CLIENT is not None:
+        return _GLOBAL_HTTP_CLIENT
+
+    try:
+        import httpx
+    except ImportError as exc:
+        raise RuntimeError("The 'httpx' package is required. Install with: uv add httpx") from exc
+
+    proxy = os.getenv("SHADOWCAT_PROXY")
+    http_kwargs: dict[str, Any] = {
+        "timeout": httpx.Timeout(30.0, connect=10.0),
+        "follow_redirects": True,
+        "headers": {"User-Agent": "ShadowCat/1.0 (+autonomous-pentest)"},
+        "verify": False,
+    }
+    if proxy:
+        http_kwargs["proxy"] = proxy
+    _GLOBAL_HTTP_CLIENT = httpx.AsyncClient(**http_kwargs)
+    return _GLOBAL_HTTP_CLIENT
+
+
+def get_shared_csrf_jar() -> dict[str, str]:
+    return _GLOBAL_CSRF_JAR
+
+
+class OpenRouterBackend(AgentBackend):
+    """
+    OpenRouter backend using the OpenAI-compatible Chat Completions API.
+
+    Runs a full agentic loop internally:
+      1. Sends the user prompt to the model.
+      2. Executes any tool calls (bash / read_file / write_file) locally.
+      3. Feeds results back and loops until the model stops calling tools.
+      4. Yields AgentMessage objects throughout so the controller / TUI see
+         a live stream of TEXT, TOOL_START, TOOL_RESULT, and RESULT events.
+
+    Required env vars:
+      OPENROUTER_API_KEY  — your OpenRouter API key
+      MODEL               — model identifier (e.g. "anthropic/claude-3-5-sonnet")
+    """
+
+    def __init__(
+        self,
+        working_directory: str,
+        system_prompt: str,
+        model: str,
+    ):
+        self._cwd = working_directory
+        self._system_prompt = system_prompt
+        self._model = model
+        self._client: Any = None  # openai.AsyncOpenAI
+        self._messages: list[dict[str, Any]] = []
+        # Tool schemas actually sent on the wire. Set in connect() to either
+        # the shared _TOOLS or a cache-flagged copy (Claude models). Default
+        # keeps the attribute valid even if a caller skips connect().
+        self._tools: list[dict[str, Any]] = _TOOLS
+        self._pending_query: str | None = None
+        # Generate a short session ID from a UUID fragment
+        import uuid
+
+        self._session_id: str = str(uuid.uuid4())[:8]
+
+        # --- Component A + B state ------------------------------------
+        # Persistent HTTP session for the http_request tool. Owns cookies,
+        # default headers, and the CSRF token jar across calls.
+        self._http: Any = None  # httpx.AsyncClient, lazily imported in connect()
+        self._csrf_jar: dict[str, str] = {}  # form_action_url -> last seen token
+        self._http_history: list[dict[str, Any]] = []  # (method, url, status)
+        from agent.parsing.html_distiller import HTMLDistiller
+
+        self._distiller = HTMLDistiller()
+
+    # ------------------------------------------------------------------
+    # AgentBackend interface
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        """Initialise the AsyncOpenAI client pointed at OpenRouter.
+
+        Model selection priority: CLI --model > MODEL env var > hardcoded default.
+        The caller (controller) is responsible for resolving that priority into
+        ``self._model`` via ShadowCatConfig; this method must NOT re-read the
+        env var, or it will silently override the CLI flag.
+        """
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as exc:
+            raise RuntimeError(
+                "The 'openai' package is required for the OpenRouter backend. "
+                "Install with: uv add openai"
+            ) from exc
+
+        api_key = os.getenv("OPENROUTER_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "OPENROUTER_API_KEY environment variable is not set. "
+                "Get a key at https://openrouter.ai/keys and add it to your .env file."
+            )
+
+        if not self._model:
+            raise RuntimeError(
+                "No model specified. Pass --model on the CLI or set MODEL in .env "
+                "(e.g. MODEL=qwen/qwen-max). Any OpenRouter model slug is accepted."
+            )
+
+        try:
+            # `timeout` here goes through the SDK into its underlying httpx
+            # client. Without it, a hung response (e.g. an oversized payload
+            # the upstream provider quietly stalls on) keeps the connection
+            # open indefinitely — that's the "Thinking… Connecting…" hang
+            # the operator sees with `--file <huge>`.
+            self._client = AsyncOpenAI(
+                base_url="https://openrouter.ai/api/v1",
+                api_key=api_key,
+                timeout=_LLM_REQUEST_TIMEOUT_SECONDS,
+                max_retries=1,  # SDK default is 2; we'd rather fail fast and let the controller decide
+            )
+        except Exception as exc:
+            raise RuntimeError(
+                f"Failed to initialise OpenRouter client for model '{self._model}': {exc}"
+            ) from exc
+
+        # Spin up the persistent HTTP session used by the http_request tool.
+        self._init_http_session()
+
+        # Mark the static prefix (system prompt + tools) cacheable for Claude
+        # models; other providers get the plain, byte-stable form they can
+        # auto-cache. See _build_cached_tools / _cacheable_system_message.
+        self._tools = _build_cached_tools(_TOOLS, self._model)
+        if _is_anthropic_model(self._model):
+            self._messages = [_cacheable_system_message(self._system_prompt)]
+        else:
+            self._messages = [{"role": "system", "content": self._system_prompt}]
+
+    def _init_http_session(self) -> None:
+        """Initialise the persistent httpx session used by the http_request tool.
+
+        Extracted out of ``connect()`` so subclasses (AnthropicBackend) can
+        reuse the same HTTP runtime without re-implementing it.
+        Proxy support: set SHADOWCAT_PROXY=http://127.0.0.1:8080 to route
+        every agent-issued HTTP request through Burp/mitmproxy.
+        """
+        self._http = get_shared_http_client()
+        self._csrf_jar = get_shared_csrf_jar()
+
+    async def _close_http_session(self) -> None:
+        """Counterpart to _init_http_session. Safe to call when already closed."""
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    async def disconnect(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.close()
+            self._client = None
+        await self._close_http_session()
+
+    async def query(self, prompt: str) -> None:
+        """Queue a user prompt to be sent on the next receive_messages iteration."""
+        self._pending_query = prompt
+
+    async def receive_messages(self) -> AsyncIterator[AgentMessage]:  # type: ignore[override]
+        """
+        Async generator that drives the agentic loop and yields AgentMessages.
+
+        Must be called after connect() and query().
+        Additional query() calls mid-iteration inject new user turns at the
+        next safe loop boundary (after tool results are delivered).
+        """
+        if self._client is None:
+            raise RuntimeError("Backend not connected — call connect() first.")
+        if self._pending_query is None:
+            return
+
+        self._messages.append({"role": "user", "content": self._pending_query})
+        self._pending_query = None
+
+        total_cost: float = 0.0
+        turn = 0
+
+        while True:
+            turn += 1
+            if turn > _MAX_AGENT_TURNS:
+                yield AgentMessage(
+                    type=MessageType.ERROR,
+                    content=(
+                        f"Agent reached max turn cap ({_MAX_AGENT_TURNS}) without "
+                        "completing. Stopping to avoid runaway cost."
+                    ),
+                )
+                break
+            await self._maybe_compact()
+            try:
+                # Hard ceiling on the round-trip. `asyncio.wait_for` cancels
+                # the underlying coroutine on timeout — httpx propagates the
+                # cancellation cleanly and the socket is closed. This is the
+                # backstop in case the SDK's own httpx timeout doesn't fire
+                # (e.g. the provider streams keepalive bytes without ever
+                # delivering a complete response).
+                with span(f"LLM turn {turn} [{self._model}]"):
+                    response = await asyncio.wait_for(
+                        self._client.chat.completions.create(
+                            model=self._model,
+                            messages=self._messages,
+                            tools=self._tools,
+                            tool_choice="auto",
+                            # Ask OpenRouter to include cost in the usage block.
+                            # Without this, `usage.cost` is never populated and the
+                            # cost counter stays at $0.0000 for the whole session.
+                            extra_body={"usage": {"include": True}},
+                        ),
+                        timeout=_LLM_WAITFOR_TIMEOUT_SECONDS,
+                    )
+            except TimeoutError:
+                yield AgentMessage(
+                    type=MessageType.ERROR,
+                    content=(
+                        f"OpenRouter API call timed out after "
+                        f"{_LLM_WAITFOR_TIMEOUT_SECONDS}s. Most likely cause: "
+                        f"the prompt is too large for model '{self._model}' "
+                        f"(check --file size) or the provider is overloaded."
+                    ),
+                )
+                return
+            except Exception as exc:
+                # Surface auth errors, rate limits, and context-overflow
+                # errors as a clean ERROR message instead of letting them
+                # bubble up as a stack trace through the spinner.
+                yield AgentMessage(
+                    type=MessageType.ERROR,
+                    content=f"OpenRouter API call failed: {exc.__class__.__name__}: {exc}",
+                )
+                return
+
+            choice = response.choices[0]
+            msg = choice.message
+
+            # Accumulate cost when the provider reports it.
+            # OpenRouter returns `cost` (USD, float) on the usage object when
+            # the request opted in via extra_body. The OpenAI SDK doesn't
+            # model this field, so it lands in `model_extra` (pydantic v2)
+            # — fall back to that if the attribute isn't directly accessible.
+            if response.usage:
+                usage = response.usage
+                cost_val = getattr(usage, "cost", None)
+                if cost_val is None:
+                    extra = getattr(usage, "model_extra", None) or {}
+                    cost_val = extra.get("cost")
+                total_cost += float(cost_val or 0)
+
+            # Store a clean assistant turn in history
+            asst_entry: dict[str, Any] = {"role": "assistant"}
+            if msg.content is not None:
+                asst_entry["content"] = msg.content
+            if msg.tool_calls:
+                asst_entry["tool_calls"] = [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {
+                            "name": tc.function.name,
+                            "arguments": tc.function.arguments,
+                        },
+                    }
+                    for tc in msg.tool_calls
+                ]
+            self._messages.append(asst_entry)
+
+            # Yield any text content
+            if msg.content:
+                yield AgentMessage(type=MessageType.TEXT, content=msg.content)
+
+            # If no tool calls: check for injected query or finish
+            if not msg.tool_calls:
+                if self._pending_query:
+                    self._messages.append({"role": "user", "content": self._pending_query})
+                    self._pending_query = None
+                    continue
+                break
+
+            # Execute tool calls concurrently. The model can emit several in a
+            # single turn (e.g. parallel recon); running them with
+            # asyncio.gather cuts wall-clock latency versus awaiting each in
+            # turn. TOOL_START events fire up front, then results are emitted
+            # and appended to history in the ORIGINAL order so the
+            # (tool_call_id -> result) pairing the API requires stays exact.
+            parsed_calls: list[tuple[Any, str, dict[str, Any]]] = []
+            for tc in msg.tool_calls:
+                name = tc.function.name
+                try:
+                    args = json.loads(tc.function.arguments)
+                except json.JSONDecodeError:
+                    args = {}
+                parsed_calls.append((tc, name, args))
+                yield AgentMessage(
+                    type=MessageType.TOOL_START,
+                    content=None,
+                    tool_name=name,
+                    tool_args=args,
+                )
+
+            with span(f"tools turn {turn} [{len(parsed_calls)} call(s)]"):
+                tool_outputs = await asyncio.gather(
+                    *(self._execute_tool(name, args) for _, name, args in parsed_calls),
+                    return_exceptions=True,
+                )
+
+            for (tc, name, _args), result in zip(parsed_calls, tool_outputs, strict=True):
+                if isinstance(result, BaseException):
+                    result = f"Tool '{name}' raised: {result!r}"
+                # Wrap untrusted tool output to prevent injection attacks
+                wrapped_result = wrap_untrusted(result, source=name)
+
+                yield AgentMessage(
+                    type=MessageType.TOOL_RESULT,
+                    content=wrapped_result,
+                    tool_name=name,
+                )
+
+                self._messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": wrapped_result,
+                    }
+                )
+
+            # Pick up any instruction injected during tool execution
+            if self._pending_query:
+                self._messages.append({"role": "user", "content": self._pending_query})
+                self._pending_query = None
+
+        yield AgentMessage(
+            type=MessageType.RESULT,
+            content=None,
+            metadata={"cost_usd": total_cost},
+        )
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    @property
+    def supports_resume(self) -> bool:
+        # Conversation history lives in memory; no server-side session to resume.
+        return False
+
+    async def resume(self, session_id: str) -> bool:
+        return False
+
+    async def _maybe_compact(self) -> None:
+        """Compact conversation history to prevent token bloat."""
+        # Cheap gate first: fewer than 8 messages can never compact (we keep
+        # system + 6 tail), so skip the expensive json.dumps on every turn.
+        if len(self._messages) <= 7:
+            return
+
+        try:
+            history_str = json.dumps(self._messages)
+        except TypeError:
+            history_str = str(self._messages)
+
+        if len(history_str) < 80000:
+            return
+
+        head = self._messages[0:1]  # System prompt
+        middle = self._messages[1:-6]
+        tail = self._messages[-6:]
+
+        middle_text = json.dumps(middle)
+        summary_prompt = (
+            "Summarize the following pentesting context. Keep crucial facts, discovered URLs, "
+            "vulnerabilities, and credentials. Be concise.\n\n" + middle_text[:50000]
+        )
+
+        try:
+            response = await asyncio.wait_for(
+                self._client.chat.completions.create(
+                    model=self._model,
+                    messages=[{"role": "user", "content": summary_prompt}],
+                ),
+                timeout=60,
+            )
+            summary = response.choices[0].message.content or ""
+        except Exception as e:
+            summary = f"Context compacted. Summary failed: {e}"
+
+        compacted_msg = {"role": "user", "content": f"<COMPACTED PRIOR CONTEXT>\n{summary}"}
+
+        self._messages = head + [compacted_msg] + tail
+
+    # ------------------------------------------------------------------
+    # Tool execution
+    # ------------------------------------------------------------------
+
+    async def _execute_tool(self, name: str, args: dict[str, Any]) -> str:
+        if name == "bash":
+            return await self._run_bash(args.get("command", ""))
+        if name == "read_file":
+            return self._read_file(args.get("path", ""))
+        if name == "write_file":
+            return self._write_file(args.get("path", ""), args.get("content", ""))
+        if name == "http_request":
+            return await self._send_http_request(args)
+        if name == "hash_crack":
+            return await self._hash_crack(args.get("hash_value", ""))
+        if name == "decode_chain":
+            return self._decode_chain(args.get("encoded_string", ""))
+        if name == "sqli_probe":
+            return await self._sqli_probe(args.get("url", ""))
+        return f"Unknown tool: {name}"
+
+    async def _hash_crack(self, hash_value: str) -> str:
+        quoted = shlex.quote(hash_value)
+        cmd = (
+            f"echo {quoted} > /tmp/target_hash.txt && "
+            "hashcat /tmp/target_hash.txt /usr/share/wordlists/rockyou.txt --potfile-disable --quiet || "
+            "john /tmp/target_hash.txt --wordlist=/usr/share/wordlists/rockyou.txt"
+        )
+        return await self._run_bash(cmd)
+
+    def _decode_chain(self, encoded_string: str) -> str:
+        import base64
+        import urllib.parse
+
+        current = encoded_string
+        decoded_path = []
+        for _ in range(10):  # Max depth
+            changed = False
+            url_dec = urllib.parse.unquote(current)
+            if url_dec != current:
+                current = url_dec
+                decoded_path.append("url")
+                changed = True
+                continue
+            try:
+                hex_dec = bytes.fromhex(current).decode("utf-8")
+                if hex_dec != current and hex_dec.isprintable():
+                    current = hex_dec
+                    decoded_path.append("hex")
+                    changed = True
+                    continue
+            except Exception:
+                pass
+            try:
+                padded = current + "=" * ((4 - len(current) % 4) % 4)
+                b64_dec = base64.b64decode(padded).decode("utf-8")
+                if b64_dec != current and b64_dec.isprintable():
+                    current = b64_dec
+                    decoded_path.append("base64")
+                    changed = True
+                    continue
+            except Exception:
+                pass
+
+            if not changed:
+                break
+
+        path_str = " -> ".join(decoded_path) if decoded_path else "none"
+        return f"Decoded ({path_str}): {current}"
+
+    async def _sqli_probe(self, url: str) -> str:
+        cmd = f"sqlmap -u {shlex.quote(url)} --batch --risk=1 --level=1"
+        return await self._run_bash(cmd)
+
+    async def _run_bash(self, command: str) -> str:
+        # Profiling: surface slow/hung shell tools (nmap, sqlmap, hashcat) in
+        # the debug log with the exact command + wall-clock, so "the agent is
+        # stuck" is attributable to a specific subprocess rather than guessed at.
+        t0 = time.perf_counter()
+        preview = command if len(command) <= 80 else command[:79] + "…"
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+                cwd=self._cwd,
+                # Drop LLM-provider API keys before they reach the child so a
+                # model-authored command can't exfiltrate them via `env`/`curl`.
+                env=scrubbed_env(),
+            )
+            stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=_TOOL_TIMEOUT_SECONDS)
+            output = stdout.decode("utf-8", errors="replace")
+            mark(f"bash done in {time.perf_counter() - t0:.2f}s: {preview!r}")
+            if len(output) > _OUTPUT_TRUNCATE_CHARS:
+                output = output[:_OUTPUT_TRUNCATE_CHARS] + "\n...[output truncated]..."
+            return output or "(no output)"
+        except TimeoutError:
+            mark(f"bash TIMEOUT after {_TOOL_TIMEOUT_SECONDS}s: {preview!r}")
+            return f"Command timed out after {_TOOL_TIMEOUT_SECONDS} seconds."
+        except Exception as exc:
+            mark(f"bash error after {time.perf_counter() - t0:.2f}s: {preview!r}")
+            return f"Error running command: {exc}"
+
+    def _read_file(self, path: str) -> str:
+        try:
+            full = Path(path) if Path(path).is_absolute() else Path(self._cwd) / path
+            content = full.read_text(encoding="utf-8", errors="replace")
+            if len(content) > _OUTPUT_TRUNCATE_CHARS:
+                content = content[:_OUTPUT_TRUNCATE_CHARS] + "\n...[file truncated]..."
+            return content
+        except Exception as exc:
+            return f"Error reading file: {exc}"
+
+    def _write_file(self, path: str, content: str) -> str:
+        try:
+            full = Path(path) if Path(path).is_absolute() else Path(self._cwd) / path
+            full.parent.mkdir(parents=True, exist_ok=True)
+            full.write_text(content, encoding="utf-8")
+            return f"Wrote {len(content)} bytes to {full}."
+        except Exception as exc:
+            return f"Error writing file: {exc}"
+
+    # ------------------------------------------------------------------
+    # http_request (Component A) + distillation (Component B) executor
+    # ------------------------------------------------------------------
+
+    # Response headers worth showing the LLM. Excludes the high-noise /
+    # low-value ones (Date, Connection, Cache-Control, Vary, Set-Cookie which
+    # is already encoded in `cookies_set`, Content-Length encoded in body_length).
+    _INTERESTING_HEADER_PREFIXES = (
+        "content-type",
+        "location",
+        "server",
+        "x-",
+        "www-authenticate",
+        "access-control",
+        "content-security-policy",
+        "strict-transport-security",
+        "set-cookie",  # we keep names in cookies_set but the full directive can leak Path/Secure flags
+        "refresh",
+        "link",
+        "etag",
+        "last-modified",
+    )
+    _NON_HTML_BODY_TRUNCATE = 4000
+
+    async def _send_http_request(self, args: dict[str, Any]) -> str:
+        """Execute one HTTP request via the persistent session.
+
+        Returns a JSON string (matches the convention used by the other tools
+        — the renderer in interface/main.py already decodes and pretty-prints
+        nested JSON tool results).
+        """
+        try:
+            import httpx
+        except ImportError:
+            return json.dumps({"error": "httpx not installed in container"})
+
+        if self._http is None:
+            return json.dumps(
+                {"error": "HTTP session not initialised — backend.connect() not called"}
+            )
+
+        method = (args.get("method") or "GET").upper()
+        url = args.get("url") or ""
+        if not url:
+            return json.dumps({"error": "missing required parameter: url"})
+
+        headers = dict(args.get("headers") or {})
+        follow = bool(args.get("follow_redirects", True))
+        timeout = float(args.get("timeout_seconds") or 30)
+
+        # Body assembly. Three mutually-exclusive options: form > json_body > body.
+        # Tool description tells the LLM they're mutually exclusive; if it
+        # passes multiple we honour this priority order and silently ignore
+        # the others (httpx would 500 otherwise on conflicting kwargs).
+        content: str | None = None
+        data: dict[str, Any] | None = None
+        json_body: Any = None
+        form_arg = args.get("form")
+        json_arg = args.get("json_body")
+
+        if form_arg is not None:
+            data = dict(form_arg)
+            # Auto-CSRF: if the form action is known and the payload doesn't
+            # already carry a token field, inject the cached one.
+            if args.get("auto_csrf", True):
+                token = self._csrf_jar.get(url)
+                if token:
+                    # Use the first common token name unless the form already
+                    # has one. This is best-effort; if the framework expects a
+                    # specific name not in this list, the LLM can pass it
+                    # explicitly in `form` and we won't clobber.
+                    has_token_field = any(
+                        k.lower()
+                        in {
+                            "csrf_token",
+                            "csrf",
+                            "_token",
+                            "csrfmiddlewaretoken",
+                            "authenticity_token",
+                            "__requestverificationtoken",
+                            "xsrf_token",
+                        }
+                        for k in data
+                    )
+                    if not has_token_field:
+                        data["csrf_token"] = token
+        elif json_arg is not None:
+            json_body = json_arg
+        elif args.get("body") is not None:
+            content = args["body"]
+
+        t0 = time.perf_counter()
+        try:
+            resp = await self._http.request(
+                method,
+                url,
+                headers=headers,
+                content=content,
+                data=data,
+                json=json_body,
+                follow_redirects=follow,
+                timeout=timeout,
+            )
+        except httpx.TimeoutException as e:
+            return json.dumps(
+                {
+                    "error": "timeout",
+                    "detail": str(e),
+                    "url": url,
+                    "elapsed_ms": int((time.perf_counter() - t0) * 1000),
+                }
+            )
+        except httpx.RequestError as e:
+            return json.dumps(
+                {
+                    "error": e.__class__.__name__,
+                    "detail": str(e),
+                    "url": url,
+                }
+            )
+
+        elapsed_ms = int((time.perf_counter() - t0) * 1000)
+        ctype = (resp.headers.get("content-type") or "").lower()
+
+        # Body handling — distill HTML, pass JSON through (already structured),
+        # truncate other text, mark binary.
+        body_payload: Any
+        body_kind: str
+        if "html" in ctype or (ctype == "" and _looks_like_html(resp.text[:512])):
+            body_payload = self._distiller.distill(resp.text, base_url=str(resp.url))
+            body_kind = "html-distilled"
+            # Harvest CSRF tokens the distiller already extracted.
+            for action, token in body_payload.get("csrf_tokens", {}).items():
+                self._csrf_jar[action] = token
+
+            # Optional RAG hook for framework versions found in HTML
+            try:
+                # Only do RAG when there's actually a framework hint — avoids
+                # paying the (singleton) lookup on every HTML response.
+                fw = resp.headers.get("x-powered-by", "")
+                if fw:
+                    from agent.rag_module.knowledge_base import get_shared_kb
+
+                    cves = await get_shared_kb().query_framework_cves(fw, "unknown", top_k=2)
+                    if cves:
+                        body_payload["rag_cves"] = cves
+            except Exception:
+                pass
+        elif "json" in ctype:
+            body_payload = resp.text  # already structured, leave raw
+            body_kind = "json"
+        elif _is_textual(ctype):
+            body_text = resp.text
+            truncated = len(body_text) > self._NON_HTML_BODY_TRUNCATE
+            body_payload = body_text[: self._NON_HTML_BODY_TRUNCATE]
+            body_kind = "text-truncated" if truncated else "text"
+        else:
+            body_payload = None
+            body_kind = f"binary ({len(resp.content)} bytes)"
+
+        result: dict[str, Any] = {
+            "status": resp.status_code,
+            "url": str(resp.url),
+            "method": method,
+            "headers": self._filter_headers(resp.headers),
+            "body": body_payload,
+            "body_kind": body_kind,
+            "body_length_original": len(resp.content),
+            "cookies_set": [c.name for c in resp.cookies.jar],
+            "elapsed_ms": elapsed_ms,
+            "redirect_chain": [str(h.url) for h in resp.history] or None,
+            "summary_only": True,  # tells LLM this is distilled — request "body" via direct curl if needed
+        }
+
+        self._http_history.append({"method": method, "url": url, "status": resp.status_code})
+        return json.dumps(result, separators=(",", ":"), default=str)
+
+    def _filter_headers(self, headers: Any) -> dict[str, str]:
+        """Keep only headers likely to carry pentest signal."""
+        out: dict[str, str] = {}
+        for k, v in headers.items():
+            lk = k.lower()
+            if any(lk.startswith(p) for p in self._INTERESTING_HEADER_PREFIXES):
+                # Cap header value length (CSP and Permissions-Policy can be huge)
+                out[k] = v if len(v) < 400 else v[:400] + "…"
+        return out
+
+
+# Module-level helpers (kept out of the class — pure functions, no state).
+def _is_textual(content_type: str) -> bool:
+    if not content_type:
+        return True  # if server didn't say, assume text and try
+    lower = content_type.lower()
+    return any(
+        s in lower
+        for s in (
+            "text/",
+            "javascript",
+            "json",
+            "xml",
+            "x-www-form-urlencoded",
+        )
+    )
+
+
+def _looks_like_html(snippet: str) -> bool:
+    s = snippet.lstrip().lower()
+    return s.startswith(("<!doctype", "<html", "<head", "<!--", "<body"))
+
+
+# ============================================================================
+# AnthropicBackend — direct api.anthropic.com auth via ANTHROPIC_API_KEY
+# ============================================================================
+#
+# Inherits from OpenRouterBackend to reuse ALL tool execution logic
+# (bash / read_file / write_file / http_request / HTML distillation / CSRF
+# jar / proxy support). Only the LLM-talking surface (connect, disconnect,
+# query, receive_messages) is overridden because Anthropic's wire protocol
+# differs from OpenAI's:
+#
+#  - tools format: {"name", "description", "input_schema"} — no "function" wrapper
+#  - system prompt: top-level `system=` parameter, not a message
+#  - tool calls: ToolUseBlock inside response.content list (not tool_calls field)
+#  - tool results: nested in a SINGLE user message's content array
+#  - max_tokens: REQUIRED parameter, no default
+#  - cost: usage.input_tokens + usage.output_tokens (no USD figure returned)
+
+
+# Best-effort USD pricing for cost reporting. These are correct as of my
+# training cutoff and WILL go stale. If you see $0.0000 on a successful
+# session, your model isn't in this table — add it or accept token-only
+# accounting. Prices are USD per 1M tokens.
+_ANTHROPIC_PRICING: dict[str, dict[str, float]] = {
+    "claude-3-5-sonnet-20241022": {"input": 3.0, "output": 15.0},
+    "claude-3-5-sonnet-latest": {"input": 3.0, "output": 15.0},
+    "claude-3-5-haiku-20241022": {"input": 0.80, "output": 4.0},
+    "claude-3-5-haiku-latest": {"input": 0.80, "output": 4.0},
+    "claude-3-opus-20240229": {"input": 15.0, "output": 75.0},
+    "claude-sonnet-4-20250514": {"input": 3.0, "output": 15.0},
+    "claude-sonnet-4-5": {"input": 3.0, "output": 15.0},
+    "claude-opus-4-20250514": {"input": 15.0, "output": 75.0},
+}
+
+
+def _anthropic_tools_from_openai_schema(openai_tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Convert _TOOLS (OpenAI function-calling format) to Anthropic format.
+
+    OpenAI: {"type":"function","function":{"name","description","parameters"}}
+    Anthropic: {"name","description","input_schema"}
+    """
+    out: list[dict[str, Any]] = []
+    for t in openai_tools:
+        if t.get("type") != "function":
+            continue
+        fn = t["function"]
+        out.append(
+            {
+                "name": fn["name"],
+                "description": fn.get("description", ""),
+                "input_schema": fn.get("parameters", {"type": "object", "properties": {}}),
+            }
+        )
+    return out
+
+
+def _cacheable_anthropic_system(system_prompt: str) -> list[dict[str, Any]]:
+    """Anthropic ``system`` param as a single cache-flagged text block.
+
+    Anthropic accepts ``system`` as a string OR a list of content blocks; the
+    list form is the only one that can carry ``cache_control``.
+    """
+    return [
+        {
+            "type": "text",
+            "text": system_prompt,
+            "cache_control": _CACHE_CONTROL_EPHEMERAL,
+        }
+    ]
+
+
+class AnthropicBackend(OpenRouterBackend):
+    """Talks to api.anthropic.com directly with an ANTHROPIC_API_KEY.
+
+    Selected by the controller when ``SHADOWCAT_AUTH_MODE`` is ``anthropic``
+    or ``claude_subscription``. Session tokens (sk-ant-sid-...) are not
+    supported by the Anthropic API and were removed from config.sh.
+
+    The reuse-via-inheritance trick: tool execution (bash, read_file,
+    write_file, http_request) and HTTP session management live on the parent
+    class; we override only what's different about the LLM wire protocol.
+    """
+
+    _MAX_TOKENS_PER_RESPONSE = 4096  # Anthropic requires this be set explicitly
+
+    async def connect(self) -> None:
+        """Initialise the Anthropic client and the shared HTTP session."""
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError as exc:
+            raise RuntimeError(
+                "The 'anthropic' package is required for the AnthropicBackend. "
+                "Install with: uv add anthropic"
+            ) from exc
+
+        api_key = os.getenv("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise RuntimeError(
+                "ANTHROPIC_API_KEY environment variable is not set. "
+                "Get a key at https://console.anthropic.com/settings/keys "
+                "and add it to your .env.auth file via `make config` option [4]."
+            )
+        if not api_key.startswith("sk-ant-api"):
+            # Session tokens (sk-ant-sid-) won't authenticate against the API.
+            # Catch this loudly here rather than letting the user see a generic 401.
+            raise RuntimeError(
+                "ANTHROPIC_API_KEY does not start with 'sk-ant-api'. The "
+                "Anthropic API only accepts API keys, not session tokens. "
+                "If you have a session token (sk-ant-sid-...), it won't "
+                "work here — get a real API key at "
+                "https://console.anthropic.com/settings/keys."
+            )
+        if not self._model:
+            raise RuntimeError(
+                "No model specified. Pass --model on the CLI or set MODEL in "
+                ".env.auth (e.g. MODEL=claude-3-5-sonnet-latest). For the "
+                "Anthropic backend, use plain Claude model names without the "
+                "'anthropic/' prefix that OpenRouter expects."
+            )
+
+        try:
+            # Same rationale as OpenRouterBackend.connect(): a configured
+            # client-level timeout prevents indefinite hangs when the API
+            # stalls mid-request (oversized prompt, network blip, etc.).
+            self._client = AsyncAnthropic(
+                api_key=api_key,
+                timeout=_LLM_REQUEST_TIMEOUT_SECONDS,
+                max_retries=1,
+            )
+        except Exception as exc:
+            raise RuntimeError(
+                f"Failed to initialise Anthropic client for model '{self._model}': {exc}"
+            ) from exc
+
+        # Tool execution runtime (shared with OpenRouterBackend)
+        self._init_http_session()
+
+        # Anthropic does NOT use system messages in the messages list.
+        # The system prompt is a top-level parameter on every call.
+        # Conversation history holds only user/assistant exchanges.
+        self._messages = []
+
+    async def disconnect(self) -> None:
+        """Close both clients."""
+        if self._client is not None:
+            # AsyncAnthropic exposes aclose() in recent SDKs
+            close = getattr(self._client, "aclose", None) or getattr(self._client, "close", None)
+            if close is not None:
+                result = close()
+                if hasattr(result, "__await__"):
+                    await result
+            self._client = None
+        await self._close_http_session()
+
+    async def _maybe_compact(self) -> None:
+        """Compact conversation history for Anthropic."""
+        # Cheap gate first: skip the expensive json.dumps unless we might
+        # actually compact.
+        if len(self._messages) <= 6:
+            return
+
+        try:
+            history_str = json.dumps(self._messages, default=str)
+        except TypeError:
+            history_str = str(self._messages)
+
+        if len(history_str) < 80000:
+            return
+
+        middle = self._messages[:-6]
+        tail = self._messages[-6:]
+
+        middle_text = str(middle)
+        summary_prompt = (
+            "Summarize the following pentesting context. Keep crucial facts, discovered URLs, "
+            "vulnerabilities, and credentials. Be concise.\n\n" + middle_text[:50000]
+        )
+
+        try:
+            response = await asyncio.wait_for(
+                self._client.messages.create(
+                    model=self._model,
+                    max_tokens=self._MAX_TOKENS_PER_RESPONSE,
+                    system="You are a helpful summarization assistant.",
+                    messages=[{"role": "user", "content": summary_prompt}],
+                ),
+                timeout=60,
+            )
+            summary = response.content[0].text if response.content else ""
+        except Exception as e:
+            summary = f"Context compacted. Summary failed: {e}"
+
+        compacted_msg = {"role": "user", "content": f"<COMPACTED PRIOR CONTEXT>\n{summary}"}
+
+        self._messages = [compacted_msg] + tail
+
+    async def receive_messages(self) -> AsyncIterator[AgentMessage]:  # type: ignore[override]
+        """Drive the agentic loop using Anthropic's message API.
+
+        Differences from the parent implementation:
+          - System prompt is a top-level kwarg, not a message
+          - Tool calls live in response.content as ToolUseBlock instances
+          - Tool results go in a SINGLE user message's content array (not
+            separate messages per tool, the way OpenAI does it)
+          - Loop terminates when stop_reason != "tool_use"
+        """
+        if self._client is None:
+            raise RuntimeError("Backend not connected — call connect() first.")
+        if self._pending_query is None:
+            return
+
+        self._messages.append({"role": "user", "content": self._pending_query})
+        self._pending_query = None
+
+        anthropic_tools = _anthropic_tools_from_openai_schema(_TOOLS)
+        # Cache breakpoint on the last tool → the whole (stable) tool block is
+        # cached. The system block is cached separately in the create() call
+        # below, so the cached prefix spans tools + system on every turn.
+        if anthropic_tools:
+            anthropic_tools[-1] = {
+                **anthropic_tools[-1],
+                "cache_control": _CACHE_CONTROL_EPHEMERAL,
+            }
+        pricing = _ANTHROPIC_PRICING.get(self._model, {})
+        total_cost: float = 0.0
+        total_in_tokens = 0
+        total_out_tokens = 0
+        turn = 0
+
+        while True:
+            turn += 1
+            if turn > _MAX_AGENT_TURNS:
+                yield AgentMessage(
+                    type=MessageType.ERROR,
+                    content=(
+                        f"Agent reached max turn cap ({_MAX_AGENT_TURNS}) without "
+                        "completing. Stopping to avoid runaway cost."
+                    ),
+                )
+                break
+            await self._maybe_compact()
+            try:
+                with span(f"LLM turn {turn} [{self._model}]"):
+                    response = await asyncio.wait_for(
+                        self._client.messages.create(
+                            model=self._model,
+                            max_tokens=self._MAX_TOKENS_PER_RESPONSE,
+                            system=_cacheable_anthropic_system(self._system_prompt),
+                            messages=self._messages,
+                            tools=anthropic_tools,
+                        ),
+                        timeout=_LLM_WAITFOR_TIMEOUT_SECONDS,
+                    )
+            except TimeoutError:
+                yield AgentMessage(
+                    type=MessageType.ERROR,
+                    content=(
+                        f"Anthropic API call timed out after "
+                        f"{_LLM_WAITFOR_TIMEOUT_SECONDS}s. Most likely cause: "
+                        f"the prompt is too large for model '{self._model}' "
+                        f"(check --file size) or the provider is overloaded."
+                    ),
+                )
+                return
+            except Exception as exc:
+                # Surface auth errors and rate limits clearly to the UI layer
+                yield AgentMessage(
+                    type=MessageType.ERROR,
+                    content=f"Anthropic API call failed: {exc.__class__.__name__}: {exc}",
+                )
+                return
+
+            # Accumulate token + cost accounting
+            if response.usage:
+                in_t = response.usage.input_tokens
+                out_t = response.usage.output_tokens
+                total_in_tokens += in_t
+                total_out_tokens += out_t
+                if pricing:
+                    total_cost += (
+                        in_t * pricing["input"] / 1_000_000 + out_t * pricing["output"] / 1_000_000
+                    )
+
+            # Persist the assistant turn — content blocks must survive
+            # round-trip back to Anthropic. The SDK objects are pydantic
+            # models; we serialise via model_dump for storage safety.
+            asst_content_dumped = [
+                block.model_dump() if hasattr(block, "model_dump") else block
+                for block in response.content
+            ]
+            self._messages.append({"role": "assistant", "content": asst_content_dumped})
+
+            # Emit text blocks in order, then run all tool_use blocks
+            # concurrently. Anthropic interleaves text and tool_use in
+            # response.content; text is surfaced immediately while the tool
+            # calls fan out via asyncio.gather. Results are paired back by
+            # tool_use_id and appended in original order.
+            tool_results: list[dict[str, Any]] = []
+            tool_uses: list[Any] = []
+            for block in response.content:
+                btype = getattr(block, "type", None)
+
+                if btype == "text":
+                    text = getattr(block, "text", "") or ""
+                    if text:
+                        yield AgentMessage(type=MessageType.TEXT, content=text)
+
+                elif btype == "tool_use":
+                    name = block.name
+                    args = block.input if isinstance(block.input, dict) else {}
+                    tool_uses.append(block)
+
+                    yield AgentMessage(
+                        type=MessageType.TOOL_START,
+                        content=None,
+                        tool_name=name,
+                        tool_args=args,
+                    )
+
+            if tool_uses:
+                with span(f"tools turn {turn} [{len(tool_uses)} call(s)]"):
+                    tool_outputs = await asyncio.gather(
+                        *(
+                            self._execute_tool(b.name, b.input if isinstance(b.input, dict) else {})
+                            for b in tool_uses
+                        ),
+                        return_exceptions=True,
+                    )
+
+                for block, result in zip(tool_uses, tool_outputs, strict=True):
+                    if isinstance(result, BaseException):
+                        result = f"Tool '{block.name}' raised: {result!r}"
+                    # Wrap untrusted tool output to prevent injection attacks
+                    wrapped_result = wrap_untrusted(result, source=block.name)
+
+                    yield AgentMessage(
+                        type=MessageType.TOOL_RESULT,
+                        content=wrapped_result,
+                        tool_name=block.name,
+                    )
+
+                    tool_results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": block.id,
+                            "content": wrapped_result,
+                        }
+                    )
+
+            # Continuation decision — Anthropic tells us via stop_reason
+            if response.stop_reason == "tool_use" and tool_results:
+                # ALL tool results go in ONE user message — this is the
+                # structural difference from OpenAI's per-result messages.
+                self._messages.append({"role": "user", "content": tool_results})
+
+                # Inject any user query that arrived during tool execution
+                if self._pending_query:
+                    self._messages.append({"role": "user", "content": self._pending_query})
+                    self._pending_query = None
+                continue
+
+            # No tools called this turn — check for an injected user message
+            if self._pending_query:
+                self._messages.append({"role": "user", "content": self._pending_query})
+                self._pending_query = None
+                continue
+
+            # Conversation turn truly complete
+            break
+
+        yield AgentMessage(
+            type=MessageType.RESULT,
+            content=None,
+            metadata={
+                "cost_usd": total_cost,
+                "input_tokens": total_in_tokens,
+                "output_tokens": total_out_tokens,
+                "model": self._model,
+                "pricing_known": bool(pricing),
+            },
+        )
+
+
+# ============================================================================
+# ClaudeSDKBackend — Option 4 (Claude Subscription via OAuth)
+# ============================================================================
+#
+# Wraps `claude-agent-sdk` to drive the agentic loop under the user's
+# Claude Pro / Team subscription. Auth is handled by the SDK (OAuth via
+# `claude login` — token cached at ~/.claude/). No API key required.
+#
+# Mirrors upstream shadowcat-dast's ClaudeCodeBackend almost line-for-line,
+# adapted to our AgentBackend interface. Direct subclass of AgentBackend
+# (NOT OpenRouterBackend) because tool execution, message history, and HTTP
+# session are all owned by the SDK — there's nothing to inherit.
+#
+# Known limitations (documented honestly, not hidden):
+#   - Our custom http_request tool with HTML distillation is NOT available;
+#     the SDK provides its own WebFetch which returns raw HTML. If you need
+#     distillation in this backend, file a follow-up to register http_request
+#     as a custom SDK tool.
+#   - Only TOOL_START events are emitted, never TOOL_RESULT — the SDK runs
+#     tools internally and doesn't expose results to the host. Flag detection
+#     in raw tool output (controller.py TOOL_RESULT branch) will not fire for
+#     this backend; only flags in the agent's narration text are caught.
+
+
+class ClaudeSDKBackend(AgentBackend):
+    """Drives Claude through the official `claude-agent-sdk` (OAuth-backed).
+
+    Selected by the controller when ``SHADOWCAT_AUTH_MODE=claude_subscription``.
+    """
+
+    def __init__(
+        self,
+        working_directory: str,
+        system_prompt: str,
+        model: str,
+        permission_mode: str = "bypassPermissions",
+    ):
+        self._cwd = working_directory
+        self._system_prompt = system_prompt
+        self._model = model
+        # bypassPermissions skips the SDK's interactive permission prompts —
+        # mandatory for autonomous operation. acceptEdits is a safer alternative
+        # if you want the agent to ask before destructive actions.
+        self._permission_mode = permission_mode
+        self._client: Any = None  # claude_agent_sdk.ClaudeSDKClient
+        self._session_id: str | None = None
+
+    # ------------------------------------------------------------------
+    # Auth env-var preparation
+    # ------------------------------------------------------------------
+    #
+    # The SDK picks its auth source automatically based on env vars:
+    #   - ANTHROPIC_API_KEY present     -> uses that key (metered billing)
+    #   - ANTHROPIC_API_KEY absent      -> falls back to OAuth from `claude login`
+    #     (= Claude Pro/Team subscription, the whole point of this backend)
+    #
+    # So for Option 4 we deliberately clear ANTHROPIC_API_KEY before launching
+    # the SDK, even if the user has one set in their shell. This is the
+    # same trick upstream uses.
+
+    def _build_env_overrides(self) -> dict[str, str]:
+        """Build the env dict to pass to the SDK's subprocess.
+
+        CRITICAL: ClaudeAgentOptions.env= uses Python subprocess semantics —
+        the dict REPLACES the child's environment, it does NOT merge with
+        the parent's. If we passed just {"ANTHROPIC_API_KEY": ""}, the
+        bundled `claude` CLI would launch with no HOME, no XDG_*, no PATH,
+        no USER — and immediately fail to find ~/.claude/.credentials.json,
+        reporting "Not logged in" even though the user IS logged in.
+
+        Fix: copy the full parent env first, THEN apply overrides on top.
+
+        (Upstream shadowcat-dast has the same latent bug — they get away with it
+        because their typical user has ANTHROPIC_API_KEY unset in the shell,
+        so the branch never fires and no env replacement happens.)
+        """
+        env = dict(os.environ)
+        if env.get("ANTHROPIC_API_KEY"):
+            # Force OAuth fallback by clearing the API key for the subprocess.
+            # The SDK treats empty string as "unset" for auth-selection purposes.
+            # We keep all other vars (HOME, PATH, XDG_*, USER, etc.) intact so
+            # the bundled CLI can find its OAuth credentials at $HOME/.claude/.
+            env["ANTHROPIC_API_KEY"] = ""
+        return env
+
+    async def connect(self) -> None:
+        try:
+            from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
+        except ImportError as exc:
+            raise RuntimeError(
+                "The 'claude-agent-sdk' package is required for the Claude "
+                "Subscription backend. Install with: uv add claude-agent-sdk\n"
+                "You also need the Claude Code CLI on PATH: "
+                "npm install -g @anthropic-ai/claude-code"
+            ) from exc
+
+        options = ClaudeAgentOptions(
+            cwd=self._cwd,
+            permission_mode=self._permission_mode,  # type: ignore[arg-type]
+            system_prompt=self._system_prompt,
+            model=self._model,
+            env=self._build_env_overrides(),
+        )
+        try:
+            self._client = ClaudeSDKClient(options=options)
+            result = self._client.connect()
+            # Some SDK versions return a coroutine, others return None — handle both.
+            if result is not None:
+                await result
+        except Exception as exc:
+            # The most common failure is "claude login required" or "Claude
+            # Code CLI not found on PATH". Re-raise with a clearer message.
+            raise RuntimeError(
+                f"Failed to start Claude Agent SDK session: {exc}\n"
+                f"  - Ensure 'claude' CLI is on PATH (try: claude --version)\n"
+                f"  - Ensure you're logged in (run: claude login)\n"
+                f"  - Verify your subscription at https://claude.ai/settings"
+            ) from exc
+
+    async def disconnect(self) -> None:
+        if self._client is not None:
+            try:
+                result = self._client.disconnect()
+                if result is not None:
+                    await result
+            except Exception:
+                # Best-effort cleanup; suppress to avoid masking earlier errors.
+                pass
+            self._client = None
+
+    async def query(self, prompt: str) -> None:
+        if self._client is None:
+            raise RuntimeError("Backend not connected — call connect() first.")
+        result = self._client.query(prompt)
+        if result is not None:
+            await result
+
+    async def receive_messages(self) -> AsyncIterator[AgentMessage]:  # type: ignore[override]
+        """Translate SDK message stream into AgentMessage events.
+
+        We import the SDK message types lazily inside the function so that
+        `import backend` doesn't hard-fail when the SDK isn't installed —
+        users of the other backends shouldn't pay that cost.
+        """
+        try:
+            from claude_agent_sdk import (
+                AssistantMessage,
+                ResultMessage,
+                TextBlock,
+                ToolUseBlock,
+            )
+        except ImportError as exc:
+            raise RuntimeError(
+                "claude-agent-sdk not available — see connect() for install hints."
+            ) from exc
+
+        if self._client is None:
+            raise RuntimeError("Backend not connected — call connect() first.")
+
+        async for msg in self._client.receive_response():
+            if isinstance(msg, AssistantMessage):
+                for block in msg.content:
+                    if isinstance(block, TextBlock):
+                        yield AgentMessage(
+                            type=MessageType.TEXT,
+                            content=block.text,
+                        )
+                    elif isinstance(block, ToolUseBlock):
+                        yield AgentMessage(
+                            type=MessageType.TOOL_START,
+                            content=None,
+                            tool_name=block.name,
+                            tool_args=block.input if isinstance(block.input, dict) else {},
+                        )
+                        # NOTE: no matching TOOL_RESULT yield — see class docstring.
+
+            elif isinstance(msg, ResultMessage):
+                yield AgentMessage(
+                    type=MessageType.RESULT,
+                    content=None,
+                    metadata={
+                        # The SDK populates this field directly when the upstream
+                        # provider reports cost. For OAuth/subscription mode this
+                        # is typically 0 because subscription usage isn't billed
+                        # per-token to the user.
+                        "cost_usd": getattr(msg, "total_cost_usd", 0) or 0,
+                        "model": self._model,
+                    },
+                )
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    @property
+    def supports_resume(self) -> bool:
+        # The SDK supports resume natively via the `resume=` option.
+        return True
+
+    async def resume(self, session_id: str) -> bool:
+        """Reconnect with a previous SDK session ID."""
+        try:
+            from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
+        except ImportError as exc:
+            raise RuntimeError("claude-agent-sdk not installed") from exc
+
+        if self._client is not None:
+            try:
+                result = self._client.disconnect()
+                if result is not None:
+                    await result
+            except Exception:
+                pass
+
+        options = ClaudeAgentOptions(
+            cwd=self._cwd,
+            permission_mode=self._permission_mode,  # type: ignore[arg-type]
+            system_prompt=self._system_prompt,
+            model=self._model,
+            resume=session_id,
+            env=self._build_env_overrides(),
+        )
+        try:
+            self._client = ClaudeSDKClient(options=options)
+            result = self._client.connect()
+            if result is not None:
+                await result
+        except Exception as exc:
+            raise RuntimeError(f"Failed to resume SDK session {session_id}: {exc}") from exc
+        self._session_id = session_id
+        return True