gdmcode 0.1.0__py3-none-any.whl

src/agent/loop.py

@@ -0,0 +1,1410 @@
+"""Agent event loop — the generator-based heart of gdm code.
+
+Drives the model-tool-model cycle. Yields AgentEvents so callers (REPL,
+daemon, tests) can react to each step without coupling to the loop internals.
+
+Design principles:
+  - TranscriptStore is the SOLE source of truth for message history.
+    _transcript.to_messages() is always passed to the API — no parallel list.
+  - One assistant Turn per model response, carrying both content and tool_calls.
+  - Budget is synced from transcript after each change, never additively tracked.
+  - All errors surface as EventType.ERROR followed by EventType.DONE; never raised.
+
+Phase 1: non-streaming, sequential tool execution.
+Phase 2 (future): streaming text deltas, parallel tool execution.
+"""
+from __future__ import annotations
+
+import concurrent.futures as _cf
+import json
+import logging
+import re
+import time
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import TYPE_CHECKING, Any, Generator
+
+from src.exceptions import ApiError, BudgetExceededError, FatalApiError
+from src.models.client import GdmClient
+from src.models.router import CircuitBreaker
+
+from src.agent.context_budget import ContextBudget, count_tokens
+from src.agent.system_prompt import build_system_prompt
+from src.agent.transcript import TranscriptStore, Turn
+from src.cost_tracker import CostTracker
+from src.models.definitions import ModelTier, Provider, get_model
+
+if TYPE_CHECKING:
+    from src.agent.tool_orchestrator import ToolOrchestrator
+    from src.config import GdmConfig
+    from src.memory.db import GdmDatabase
+    from src.models.router import ModelRouter
+
+__all__ = ["AgentEvent", "AgentLoop", "EventType", "CONFIDENCE_SCHEMA"]
+
+log = logging.getLogger(__name__)
+
+try:
+    from src.enterprise.usage_analytics import UsageAnalytics as _UsageAnalytics
+    from src.enterprise.usage_analytics import UsageEvent as _UsageEvent
+    _analytics: "_UsageAnalytics | None" = _UsageAnalytics()
+except Exception:  # noqa: BLE001
+    _analytics = None
+
+try:
+    from src.agent.risk_scorer import score_patch, RiskTier
+    _risk_scorer_available = True
+except Exception:  # noqa: BLE001
+    _risk_scorer_available = False
+
+
+def _check_patch_risk(diff, file_paths=None, autonomy_level=2):
+    """Score a patch diff and enforce risk gates based on autonomy level.
+
+    - CRITICAL (score >= block_threshold) and autonomy_level < 4: raises RuntimeError.
+    - HIGH tier and autonomy_level < 3: logs a warning (non-blocking).
+    - Always returns the PatchRiskResult (or None if scorer unavailable).
+    """
+    if not _risk_scorer_available:
+        return None
+    result = score_patch(diff, file_paths)
+    log.info("patch_risk score=%.3f tier=%s blocked=%s", result.score, result.tier, result.blocked)
+    if result.triggered_signals:
+        log.debug("patch_risk rationale:\n%s", result.rationale)
+    if result.blocked and autonomy_level < 4:
+        raise RuntimeError(f"Patch blocked: {result.rationale}")
+    if result.tier == RiskTier.HIGH and autonomy_level < 3:
+        log.warning("High-risk patch detected (score=%.3f). Review before applying:\n%s",
+                    result.score, result.rationale)
+    return result
+
+def _record_usage(
+    session_id: str,
+    actor_id: str,
+    model: str,
+    prompt_tokens: int,
+    completion_tokens: int,
+    tool_calls: int,
+) -> None:
+    """Record a usage event. Never raises."""
+    if _analytics is None:
+        return
+    try:
+        _analytics.record(
+            _UsageEvent(  # type: ignore[name-defined]
+                session_id=session_id,
+                actor_id=actor_id,
+                model=model,
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                tool_calls=tool_calls,
+            )
+        )
+    except Exception:  # noqa: BLE001
+        pass
+
+
+# Single-worker executor for async checkpoint writes — serialises DB flushes
+# so concurrent checkpoints don't interleave, and the agent thread is never blocked.
+_CHECKPOINT_EXECUTOR: _cf.ThreadPoolExecutor = _cf.ThreadPoolExecutor(
+    max_workers=1, thread_name_prefix="gdm-ckpt"
+)
+_WALL_CLOCK_CHECKPOINT_INTERVAL: float = 60.0  # seconds
+
+# File path fragments that indicate security-sensitive code and warrant extra scanning.
+_SECURITY_PATH_PATTERNS: tuple[str, ...] = (
+    "auth", "session", "password", "token", "secret", "crypto",
+    "permission", "sql", "query", "database",
+)
+
+# ---------------------------------------------------------------------------
+# Autonomy circuit breaker (module-level for testability)
+# ---------------------------------------------------------------------------
+
+_fix_attempts: dict[str, int] = {}
+
+
+def check_circuit_breaker(task_id: str, policy: "Any") -> None:
+    """Raise PermissionError if max_fix_attempts reached for *task_id*."""
+    attempts = _fix_attempts.get(task_id, 0)
+    if attempts >= policy.max_fix_attempts:
+        raise PermissionError(
+            f"Circuit breaker: {attempts} fix attempts reached for task {task_id}. Human input required."
+        )
+    _fix_attempts[task_id] = attempts + 1
+
+
+def reset_circuit_breaker(task_id: str) -> None:
+    """Clear the fix-attempt counter for *task_id*."""
+    _fix_attempts.pop(task_id, None)
+
+# JSON schema emitted to the model when requesting a confidence self-assessment.
+CONFIDENCE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["score", "reasons"],
+    "additionalProperties": False,
+    "properties": {
+        "score": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 100,
+            "description": "Confidence score 0-100 for the proposed change.",
+        },
+        "reasons": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Short bullet-point reasons justifying the score.",
+        },
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Grok native web_search spec (replaces registry spec when provider == grok)
+# ---------------------------------------------------------------------------
+
+_GROK_WEB_SEARCH_SPEC: dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "web_search",
+        "description": (
+            "Search the live web. Use for external APIs, errors not in codebase, "
+            "or unknown technology behaviour."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {"query": {"type": "string"}},
+            "required": ["query"],
+        },
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Event types
+# ---------------------------------------------------------------------------
+
+class EventType(Enum):
+    """Discriminant for AgentEvent payloads."""
+    THINKING    = auto()   # model reasoning step (text)
+    TOOL_CALL   = auto()   # model requested a tool call
+    TOOL_RESULT = auto()   # tool was executed
+    RESPONSE    = auto()   # final answer chunk from the model
+    SUBTASK     = auto()   # task decomposition for display
+    ERROR       = auto()   # tool failure or recoverable loop error
+    COST_UPDATE = auto()   # cost tracker fired
+    WARNING     = auto()   # non-fatal warning (injection, budget, etc.)
+    DONE        = auto()   # task complete
+
+
+@dataclass
+class AgentEvent:
+    """A single event emitted by AgentLoop.run()."""
+
+    type: EventType
+    content: str = ""
+    tool_name: str = ""
+    tool_call_id: str = ""
+    args: dict[str, Any] = field(default_factory=dict)
+    result: Any = None          # ToolResult | None
+    cost_usd: float = 0.0
+    turn: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Artifact auto-detection helper
+# ---------------------------------------------------------------------------
+
+
+def _should_auto_save(
+    response_text: str,
+    user_input: str,
+    *,
+    auto_detect: bool,
+) -> bool:
+    """Return True when at least 2 auto-save signals are present.
+
+    Signals:
+      (a) Explicit annotation: ``<!-- artifact -->`` in response text
+      (b) Structured block: markdown table or fenced diagram (mermaid/dot/plantuml)
+      (c) User command: ``/save`` in the current turn's user input
+
+    Auto-detection is opt-in (``auto_detect=False`` by default).  When
+    disabled, always returns ``False`` regardless of signals, preventing
+    alert fatigue.
+    """
+    if not auto_detect:
+        return False
+    signals = 0
+    if "<!-- artifact -->" in response_text:
+        signals += 1
+    if re.search(
+        r"(^\|.+\|$|```(mermaid|dot|plantuml))", response_text, re.MULTILINE
+    ):
+        signals += 1
+    if user_input.strip().startswith("/save"):
+        signals += 1
+    return signals >= 2
+
+
+# ---------------------------------------------------------------------------
+# Agent loop
+# ---------------------------------------------------------------------------
+
+class AgentLoop:
+    """Generator-based model-tool-model loop.
+
+    Callers iterate over AgentLoop.run(user_message) to receive AgentEvents.
+    TranscriptStore is the single source of truth — no parallel message list.
+
+    Usage::
+
+        loop = AgentLoop(cfg, orchestrator, transcript, budget, cost_tracker)
+        for event in loop.run("Fix the auth bug"):
+            if event.type == EventType.RESPONSE:
+                console.print(event.content)
+    """
+
+    def __init__(
+        self,
+        cfg: GdmConfig,
+        orchestrator: ToolOrchestrator,
+        transcript: TranscriptStore,
+        budget: ContextBudget,
+        cost_tracker: CostTracker,
+        *,
+        model_tier: str = ModelTier.CODER,
+        router: ModelRouter | None = None,
+        db: GdmDatabase | None = None,
+        session_id: str = "",
+        project_id: str = "",
+        circuit_breaker: CircuitBreaker | None = None,
+        continuous_memory: Any = None,
+    ) -> None:
+        self._cfg = cfg
+        self._orchestrator = orchestrator
+        self._transcript = transcript
+        self._budget = budget
+        self._cost_tracker = cost_tracker
+        self._model = get_model(model_tier, cfg.provider)
+        self._model_id = self._model.id
+        # Set proxy state before first client creation.
+        # Use isinstance guards so MagicMock configs in tests don't accidentally activate proxy.
+        _p_url = getattr(cfg, "proxy_url", "") or ""
+        _p_tok = getattr(cfg, "proxy_token", None)
+        self._proxy_active: bool = (
+            bool(getattr(cfg, "proxy_enabled", False))
+            and isinstance(_p_url, str) and bool(_p_url)
+            and isinstance(_p_tok, str) and bool(_p_tok)
+        )
+        self._proxy_url: str = _p_url if isinstance(_p_url, str) else ""
+        self._proxy_token: str = _p_tok if isinstance(_p_tok, str) else ""
+        self._gdm_client = self._make_client()
+        self._router = router
+        self._db = db
+        self._session_id = session_id
+        self._project_id = project_id
+        self._initialized = False
+        self._files_written: list[Any] = []   # Path objects from write tools this turn
+        self._model_turn_count: int = 0       # incremented each model call; drives checkpoints
+        self._last_checkpoint_at: float = 0.0  # monotonic time of last checkpoint write
+        self._checkpoint_future: "_cf.Future[None] | None" = None  # pending async checkpoint
+        self._current_event_id: str | None = None  # event log ID for the in-flight turn
+        self._git_wf: Any = None              # GitWorkflow | None — set by _try_create_task_branch
+        self._reasoning_mode: str = "auto"    # "on" | "off" | "auto" — set via /reasoning
+        self._reasoning_escalation_count: int = 0  # consecutive forced-REASONER turn counter
+        self._using_fallback: bool = False          # True once fallback provider is active
+        self._regression_guard: Any = None          # RegressionGuard | None — set externally
+        self._vg: Any = None                        # VerificationGraph | None — set externally
+        self._circuit_breaker: CircuitBreaker | None = circuit_breaker
+        self._last_compressed_at_turn: int = -10  # drives re-compression guard
+        self._continuous_memory: Any = continuous_memory  # ContinuousMemory | None
+
+    # ------------------------------------------------------------------
+    # Fallback helpers
+    # ------------------------------------------------------------------
+
+    def _make_client(self, fallback_provider: str | None = None) -> GdmClient:
+        """Create a GdmClient respecting active proxy state.
+
+        All code that rebuilds the client (init, tier switching, fallback)
+        must go through this helper so proxy mode is never silently lost.
+        When proxy is active, ALL calls go through the proxy regardless of
+        fallback provider (users in geo-restricted regions need this for
+        every call, not just the primary provider).
+        """
+        proxy_active = getattr(self, "_proxy_active", False)
+        proxy_url = getattr(self, "_proxy_url", "")
+        proxy_token = getattr(self, "_proxy_token", "")
+        if proxy_active and proxy_url and proxy_token:
+            return GdmClient.for_proxy(proxy_url, proxy_token)
+        if fallback_provider:
+            return GdmClient.for_provider(fallback_provider, self._cfg)
+        return GdmClient(self._cfg)
+
+    @staticmethod
+    def parse_confidence_response(raw: Any) -> "dict[str, Any] | None":
+        """Validate and return a confidence response dict, or None if malformed.
+
+        Accepts a dict with ``score`` (int, 0–100) and ``reasons`` (list[str]).
+        Returns None for any type mismatch, out-of-range score, or missing keys.
+        """
+        if not isinstance(raw, dict):
+            return None
+        score = raw.get("score")
+        reasons = raw.get("reasons")
+        if not isinstance(score, int) or isinstance(score, bool):
+            return None
+        if not (0 <= score <= 100):
+            return None
+        if not isinstance(reasons, list):
+            return None
+        if not all(isinstance(r, str) for r in reasons):
+            return None
+        return {"score": score, "reasons": reasons}
+
+    @staticmethod
+    def _should_try_fallback(exc: ApiError) -> bool:
+        """Return True if *exc* is a transient error that warrants a fallback."""
+        from src.exceptions import ApiRateLimitError
+        if isinstance(exc, ApiRateLimitError):
+            return True
+        # Check HTTP status if present
+        status = getattr(exc, "status_code", None) or getattr(exc, "status", None)
+        if status in (429, 500, 503):
+            return True
+        # Fall back on status embedded in the message as a last resort
+        msg = str(exc)
+        return any(f" {code}" in msg or f"={code}" in msg for code in ("429", "500", "503"))
+
+    def _switch_to_fallback(self, error: ApiError) -> str:
+        """Switch to the fallback provider (session-sticky).
+
+        Returns a human-readable notification string on success.
+
+        Raises:
+            FatalApiError: if already on the fallback (both providers failed).
+            ApiError: if no fallback is configured (re-raises *error*).
+        """
+        if self._using_fallback:
+            raise FatalApiError(
+                f"Both primary and fallback providers failed. Last error: {error}"
+            )
+        fallback = self._cfg.fallback_provider
+        if not fallback:
+            raise error  # propagate — no fallback configured
+
+        # Determine fallback model ID
+        fallback_model = self._cfg.model_id_map.get(self._model_id)
+        if not fallback_model:
+            from src.models.definitions import models_for_provider
+            fallback_models = models_for_provider(fallback)
+            if not fallback_models:
+                raise FatalApiError(
+                    f"No models available for fallback provider '{fallback}'"
+                )
+            fallback_model = fallback_models[0].id
+
+        self._gdm_client = self._make_client(fallback_provider=fallback)
+        self._model_id = fallback_model
+        self._using_fallback = True
+        log.info(
+            "API fallback: switched to provider=%s model=%s (triggered by: %s)",
+            fallback,
+            fallback_model,
+            error,
+        )
+        return (
+            f"Primary API unavailable ({error}). "
+            f"Switched to fallback provider '{fallback}' model '{fallback_model}'."
+        )
+
+    # ------------------------------------------------------------------
+    # Escalation helper
+    # ------------------------------------------------------------------
+
+    def _handle_api_error_escalation(self, exc: ApiError, turn_num: int) -> None:
+        """Classify API error, call escalate_with_context, record in circuit breaker."""
+        if self._router is None and self._circuit_breaker is None:
+            return
+        from src.models.router import EscalationContext, FailureType
+        ecx = EscalationContext(
+            current_tier=getattr(self._model, "tier", ModelTier.CODER),
+            failure_type=FailureType.API_ERROR,
+            failure_detail=str(exc),
+            attempt_number=turn_num,
+            cost_spent_usd=self._cost_tracker.session_total_usd,
+            transcript_summary="",
+        )
+        if self._router is not None:
+            self._router.escalate_with_context(ecx)
+        if self._circuit_breaker is not None:
+            self._circuit_breaker.record_escalation(self._cost_tracker.session_total_usd)
+
+    # ------------------------------------------------------------------
+    # Public runtime-control methods
+    # ------------------------------------------------------------------
+
+    def set_tier(self, tier: str) -> None:
+        """Switch the active model tier at runtime (/model command)."""
+        try:
+            self._model = get_model(tier, self._cfg.provider)
+            self._model_id = self._model.id
+            self._gdm_client = self._make_client()
+        except Exception as exc:
+            log.warning("set_tier(%r) failed: %s", tier, exc)
+
+    def set_proxy(self, url: str, token: str) -> None:
+        """Enable proxy mode — all subsequent LLM calls are routed through *url*."""
+        self._proxy_url = url
+        self._proxy_token = token
+        self._proxy_active = True
+        self._gdm_client = self._make_client()
+        log.info("Proxy mode enabled: %s", url)
+
+    def clear_proxy(self) -> None:
+        """Disable proxy mode and restore direct provider calls."""
+        self._proxy_active = False
+        self._gdm_client = self._make_client()
+        log.info("Proxy mode disabled")
+
+    # ------------------------------------------------------------------
+    # Public generator
+    # ------------------------------------------------------------------
+
+    def run(self, user_message: str) -> Generator[AgentEvent, None, None]:
+        """Main loop. Yields AgentEvent stream until task is done."""
+        if not self._initialized:
+            self._try_create_task_branch(user_message)
+        self._ensure_initialized()
+
+        # User injection check — warn-only, structural patterns only
+        from src.security import check_user_injection
+        _user_inj = check_user_injection(user_message)
+        if _user_inj.is_injected:
+            yield AgentEvent(
+                EventType.WARNING,
+                content=(
+                    f"⚠ User message matched structural injection pattern "
+                    f"({_user_inj.pattern}). Message will still be processed."
+                ),
+            )
+
+        # Dynamic model tier routing — re-pick tier based on prompt complexity
+        # Skip router when on fallback to keep session-sticky provider/model.
+        if self._router is not None and not self._using_fallback:
+            from src.models.router import TaskContext
+            ctx = TaskContext(
+                prompt=user_message,
+                token_count=self._budget.used_tokens,
+                provider=self._cfg.provider,
+            )
+            tier = self._router.select_tier_for_turn(
+                ctx,
+                reasoning_mode=self._reasoning_mode,
+            )
+            self._model = get_model(tier, self._cfg.provider)
+            self._model_id = self._model.id
+            self._gdm_client = self._make_client()
+            log.debug(
+                "ModelRouter selected tier=%s mode=%s for prompt=%r",
+                tier,
+                self._reasoning_mode,
+                user_message[:60],
+            )
+            # Cost-budget guard: warn after N consecutive forced-REASONER turns
+            if self._reasoning_mode == "on" and tier == ModelTier.REASONER:
+                self._reasoning_escalation_count += 1
+                if self._reasoning_escalation_count > 5:
+                    yield AgentEvent(
+                        EventType.COST_UPDATE,
+                        content=(
+                            f"⚠ Reasoning mode forced ON — "
+                            f"{self._reasoning_escalation_count} consecutive REASONER calls. "
+                            "Use /reasoning auto to save cost."
+                        ),
+                    )
+            else:
+                self._reasoning_escalation_count = 0
+
+        self._files_written = []  # reset per-run file tracking
+
+        self._transcript.append(
+            Turn(role="user", content=user_message, tokens=count_tokens(user_message))
+        )
+        self._budget.sync_from_transcript(self._transcript)
+
+        max_turns = self._cfg.max_turns
+        for turn_num in range(max_turns):
+            # Cost guard — soft limit from config
+            if self._cost_tracker.exceeds(self._cfg.cost_limit_usd):
+                yield AgentEvent(EventType.ERROR, content="Cost limit exceeded", turn=turn_num)
+                yield AgentEvent(EventType.DONE, turn=turn_num)
+                return
+            # Circuit breaker guard
+            if self._circuit_breaker is not None and self._circuit_breaker.should_halt():
+                yield AgentEvent(EventType.ERROR,
+                                 content=self._circuit_breaker.halt_reason(), turn=turn_num)
+                yield AgentEvent(EventType.DONE, turn=turn_num)
+                return
+            # Budget enforcement — hard-stop limit from DB
+            if self._db is not None:
+                try:
+                    self._cost_tracker.check_budget(self._db)
+                except BudgetExceededError as exc:
+                    yield AgentEvent(EventType.ERROR, content=str(exc), turn=turn_num)
+                    yield AgentEvent(EventType.DONE, turn=turn_num)
+                    return
+
+            self._model_turn_count += 1
+            if (self._model_turn_count % 5 == 0
+                    or time.monotonic() - self._last_checkpoint_at > _WALL_CLOCK_CHECKPOINT_INTERVAL):
+                self._checkpoint()
+
+            # Begin event log entry for this turn
+            self._current_event_id = self._event_log_begin(
+                turn_num, user_message if turn_num == 0 else None
+            )
+
+            # Compress if needed BEFORE building the API payload
+            self._maybe_compress(turn_num)
+
+            # Drain BTW queue — inject any pending out-of-band messages as user turns
+            if self._db is not None and self._session_id:
+                try:
+                    pending_btw = self._db.btw_dequeue_pending(self._session_id)
+                    if pending_btw:
+                        for btw in pending_btw:
+                            self._transcript.append(
+                                Turn(
+                                    role="user",
+                                    content=f"[OUT-OF-BAND NOTE]: {btw['message']}",
+                                    tokens=count_tokens(btw["message"]),
+                                )
+                            )
+                        self._db.btw_mark_delivered([b["id"] for b in pending_btw])
+                        log.debug("Injected %d BTW message(s) into transcript", len(pending_btw))
+                except Exception as _btw_exc:  # noqa: BLE001
+                    log.warning("BTW queue drain failed: %s", _btw_exc)
+
+            tools = self._build_tool_specs()
+            try:
+                response = self._gdm_client.complete(
+                    self._transcript.to_messages(),
+                    model=self._model_id,
+                    tools=tools if tools else None,
+                )
+            except ApiError as exc:
+                # For 429/500/503, attempt a one-time provider fallback
+                if self._should_try_fallback(exc):
+                    try:
+                        switch_msg = self._switch_to_fallback(exc)
+                    except FatalApiError as fatal_exc:
+                        yield AgentEvent(EventType.ERROR, content=str(fatal_exc), turn=turn_num)
+                        self._checkpoint()
+                        self._flush_checkpoint_sync()
+                        yield AgentEvent(EventType.DONE, turn=turn_num)
+                        return
+                    except ApiError:
+                        # No fallback configured — propagate original error
+                        yield AgentEvent(EventType.ERROR, content=str(exc), turn=turn_num)
+                        self._checkpoint()
+                        self._flush_checkpoint_sync()
+                        yield AgentEvent(EventType.DONE, turn=turn_num)
+                        return
+                    # Switched successfully — notify and retry with fallback
+                    yield AgentEvent(EventType.THINKING, content=switch_msg, turn=turn_num)
+                    try:
+                        response = self._gdm_client.complete(
+                            self._transcript.to_messages(),
+                            model=self._model_id,
+                            tools=tools if tools else None,
+                        )
+                    except ApiError as retry_exc:
+                        yield AgentEvent(EventType.ERROR, content=str(retry_exc), turn=turn_num)
+                        self._checkpoint()
+                        self._flush_checkpoint_sync()
+                        yield AgentEvent(EventType.DONE, turn=turn_num)
+                        return
+                else:
+                    self._handle_api_error_escalation(exc, turn_num)
+                    yield AgentEvent(EventType.ERROR, content=str(exc), turn=turn_num)
+                    self._checkpoint()
+                    self._flush_checkpoint_sync()
+                    yield AgentEvent(EventType.DONE, turn=turn_num)
+                    return
+
+            choice = response.choices[0]
+            msg = choice.message
+            finish_reason = choice.finish_reason
+
+            # Record cost
+            yield from self._record_cost(response, turn_num)
+
+            # --- Build ONE unified assistant turn (content + tool_calls combined) ---
+            raw_tool_calls: list[dict[str, Any]] | None = None
+            if msg.tool_calls:
+                raw_tool_calls = [
+                    {
+                        "id": tc.id,
+                        "type": "function",
+                        "function": {
+                            "name": tc.function.name,
+                            "arguments": tc.function.arguments,
+                        },
+                    }
+                    for tc in msg.tool_calls
+                ]
+
+            asst_content = msg.content or ""
+            # Complete event log entry with token counts and response text
+            if self._db is not None and self._current_event_id:
+                try:
+                    _usage = response.usage
+                    _in_tok = getattr(_usage, "prompt_tokens", 0) or 0 if _usage else 0
+                    _out_tok = getattr(_usage, "completion_tokens", 0) or 0 if _usage else 0
+                    self._db.event_log_complete_turn(
+                        self._current_event_id, asst_content,
+                        _in_tok, _out_tok, 0,
+                        self._cost_tracker.session_total_usd,
+                    )
+                except Exception as _exc:  # noqa: BLE001
+                    log.debug("event_log_complete_turn: %s", _exc)
+            asst_tokens = count_tokens(
+                asst_content + (json.dumps(raw_tool_calls) if raw_tool_calls else "")
+            )
+            self._transcript.append(Turn(
+                role="assistant",
+                content=asst_content,
+                tokens=asst_tokens,
+                tool_calls=raw_tool_calls,
+            ))
+            self._budget.sync_from_transcript(self._transcript)
+
+            # Emit text response
+            if asst_content:
+                yield AgentEvent(EventType.RESPONSE, content=asst_content, turn=turn_num)
+
+            # Execute tool calls
+            if raw_tool_calls:
+                # Guard: finish_reason=tool_calls with empty list → infinite loop
+                if not msg.tool_calls:
+                    yield AgentEvent(EventType.ERROR, turn=turn_num,
+                                     content="finish_reason=tool_calls but no tool_calls in response")
+                    yield AgentEvent(EventType.DONE, turn=turn_num)
+                    return
+
+                yield from self._execute_tool_calls(msg.tool_calls, turn_num)
+                continue  # loop back to model with tool results
+
+            # Natural completion
+            if finish_reason in ("stop", "end_turn", None):
+                # Self-critique before finishing if any files were written this run
+                if self._files_written:
+                    yield from self._run_self_critique(turn_num)
+                    yield from self._maybe_review_gate(turn_num)
+                self._checkpoint()
+                self._flush_checkpoint_sync()
+                if self._db is not None and self._session_id:
+                    try:
+                        self._db.session_set_status(self._session_id, "complete")
+                    except Exception as exc:  # noqa: BLE001
+                        log.debug("session_set_status complete: %s", exc)
+                self._git_checkpoint_on_completion()
+                yield AgentEvent(EventType.DONE, turn=turn_num)
+                return
+
+            # Unexpected finish reason
+            yield AgentEvent(EventType.ERROR, turn=turn_num,
+                             content=f"Unexpected finish_reason: {finish_reason!r}")
+            self._checkpoint()
+            self._flush_checkpoint_sync()
+            yield AgentEvent(EventType.DONE, turn=turn_num)
+            return
+
+        yield AgentEvent(EventType.ERROR, turn=max_turns - 1,
+                         content=f"Max turns ({max_turns}) reached without completion")
+        self._checkpoint()
+        self._flush_checkpoint_sync()
+        yield AgentEvent(EventType.DONE, turn=max_turns - 1)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _try_create_task_branch(self, user_message: str = "") -> None:
+        """Attempt to create a gdm task branch for this session.
+
+        Called once before the first run() turn. Silently no-ops if:
+        - project_root is not a git repo
+        - git is unavailable
+        - we're already on a gdm/* branch
+        - the working tree is dirty (warn only — don't block)
+        """
+        try:
+            from src.git_workflow import GitWorkflow
+            wf = GitWorkflow(self._cfg.project_root)
+            if not wf.is_git_repo():
+                return
+            current = wf.current_branch()
+            if current.startswith("gdm/"):
+                # Already on a task branch (resumed session)
+                self._git_wf = wf
+                return
+            if not wf.is_clean():
+                # Dirty tree: don't create a branch (rollback would be unsafe).
+                # Still set _git_wf so /diff and /commit work, just skip branch.
+                log.info(
+                    "git: working tree has uncommitted changes — skipping task branch creation"
+                )
+                self._git_wf = wf
+                return
+            # Derive slug from session_id + first few words of message
+            slug_src = (user_message[:40] if user_message else self._session_id[:8])
+            wf.create_task_branch(slug_src)
+            self._git_wf = wf
+            log.info("git: task branch created from '%s'", current)
+        except Exception as exc:  # noqa: BLE001
+            log.debug("Git task branch skipped (non-git or no commits): %s", exc)
+
+    def _ensure_initialized(self) -> None:
+        """Inject system prompt on first run (idempotent)."""
+        if self._initialized:
+            return
+        from src.tools import REGISTRY
+        prompt = build_system_prompt(
+            self._cfg,
+            REGISTRY.all_tools(),
+            db=self._db,
+            project_id=self._project_id,
+        )
+        tokens = count_tokens(prompt)
+        self._transcript.prepend_system(prompt, tokens)
+        self._budget.sync_from_transcript(self._transcript)
+        self._initialized = True
+        if self._db is not None and self._session_id:
+            try:
+                self._db.session_set_status(self._session_id, "active")
+            except Exception as exc:  # noqa: BLE001
+                log.debug("session_set_status active: %s", exc)
+
+    def _build_tool_specs(self) -> list[dict[str, Any]]:
+        """Return tool specs for the API call.
+
+        For Grok: replace any registry web_search with the native Grok spec
+        (same name — provider handles it differently natively).
+        """
+        specs = self._orchestrator.get_permitted_specs()
+        if self._cfg.provider == Provider.GROK:
+            # Drop registry web_search (if present) and inject native Grok spec
+            specs = [s for s in specs if s.get("function", {}).get("name") != "web_search"]
+            specs = specs + [_GROK_WEB_SEARCH_SPEC]
+        return specs
+
+    def _record_cost(
+        self, response: Any, turn_num: int
+    ) -> Generator[AgentEvent, None, None]:
+        usage = response.usage
+        if usage is None:
+            return
+        in_tok = getattr(usage, "prompt_tokens", 0) or 0
+        out_tok = getattr(usage, "completion_tokens", 0) or 0
+        self._cost_tracker.record(
+            tier=self._model.tier,  # type: ignore[arg-type]
+            input_tokens=in_tok,
+            output_tokens=out_tok,
+        )
+        _record_usage(
+            session_id=self._session_id or "unknown",
+            actor_id=getattr(self._cfg, "actor_id", None) or "unknown",
+            model=self._model_id,
+            prompt_tokens=in_tok,
+            completion_tokens=out_tok,
+            tool_calls=0,
+        )
+        yield AgentEvent(EventType.COST_UPDATE,
+                         cost_usd=self._cost_tracker.session_total_usd,
+                         turn=turn_num)
+
+    def _execute_tool_calls(
+        self, tool_calls: list[Any], turn_num: int
+    ) -> Generator[AgentEvent, None, None]:
+        """Execute each tool call and append results to transcript."""
+        from pathlib import Path as _Path
+        from src._internal.constants import _WRITE_TOOLS  # noqa: PLC0415
+        for call_index, tc in enumerate(tool_calls):
+            tool_name = tc.function.name
+            tool_call_id = tc.id
+
+            try:
+                args: dict[str, Any] = json.loads(tc.function.arguments or "{}")
+            except json.JSONDecodeError:
+                args = {}
+                log.warning("Malformed JSON args for %r — using {}", tool_name)
+
+            yield AgentEvent(EventType.TOOL_CALL, tool_name=tool_name,
+                             tool_call_id=tool_call_id, args=args, turn=turn_num)
+
+            # Pre-write: capture regression baseline before the edit
+            is_write = tool_name in _WRITE_TOOLS
+            baseline = None
+            pre_write_path: str = ""
+            if is_write and self._regression_guard is not None:
+                pre_write_path = (
+                    args.get("path") or args.get("file_path") or ""
+                )
+                if pre_write_path:
+                    try:
+                        baseline = self._regression_guard.capture_baseline(
+                            _Path(pre_write_path)
+                        )
+                    except Exception as _rg_exc:  # noqa: BLE001
+                        log.debug("regression baseline capture failed: %s", _rg_exc)
+
+            # warn-only verification graph precondition gate
+            if is_write and getattr(self, "_vg", None) is not None:
+                _vg_p = args.get("path") or args.get("file_path") or ""
+                if _vg_p and self._session_id:
+                    try:
+                        _unsafe = self._vg.check_edit_preconditions(self._session_id, _vg_p)
+                        if _unsafe:
+                            log.warning("[vg] prior edits lack verification for %s: %s", _vg_p, _unsafe)
+                    except Exception as _vge:  # noqa: BLE001
+                        log.debug("vg precondition check: %s", _vge)
+            tool_result = self._orchestrator.execute(tool_name, args,
+                                                     model_id=self._model_id)
+
+            yield AgentEvent(EventType.TOOL_RESULT, tool_name=tool_name,
+                             tool_call_id=tool_call_id, result=tool_result,
+                             turn=turn_num)
+
+            # Log tool call to event log
+            if self._db is not None and self._current_event_id:
+                try:
+                    self._db.event_log_record_tool_call(
+                        self._current_event_id, call_index,
+                        tool_name, tool_call_id, args,
+                        result={"output": (tool_result.output or "")[:500],
+                                "error": tool_result.error},
+                        ok=tool_result.error is None,
+                        error=tool_result.error,
+                    )
+                except Exception as _exc:  # noqa: BLE001
+                    log.debug("event_log_record_tool_call: %s", _exc)
+            # Also count premium tool calls for budget tracking
+            self._cost_tracker.record_tool_call(tool_name)
+
+            result_content = tool_result.as_message_content()
+
+            # Post-write quality checks for successful file writes
+            if is_write and tool_result.error is None:
+                # Prefer metadata["path"] (resolved), fall back to args
+                path_arg = (
+                    (tool_result.metadata or {}).get("path")
+                    or args.get("path")
+                    or args.get("file_path")
+                    or ""
+                )
+                if path_arg:
+                    self._files_written.append(_Path(path_arg))
+                    # Log patch to event log
+                    if self._db is not None and self._current_event_id:
+                        try:
+                            patch_text = args.get("content") or args.get("new_content") or ""
+                            self._db.event_log_record_patch(
+                                self._current_event_id, path_arg,
+                                str(patch_text)[:10_000],
+                            )
+                        except Exception as _exc:  # noqa: BLE001
+                            log.debug("event_log_record_patch: %s", _exc)
+                    quality_note = self._auto_quality(path_arg)
+                    if quality_note:
+                        result_content += f"\n\n{quality_note}"
+
+                    # Log to continuous memory (non-fatal); use getattr for backward compat
+                    # with tests that use AgentLoop.__new__ without calling __init__.
+                    _cm = getattr(self, "_continuous_memory", None)
+                    if _cm is not None:
+                        try:
+                            _cm.log_decision(
+                                self._session_id,
+                                path_arg,
+                                tool_name,
+                                path_arg,
+                                turn_num,
+                            )
+                            _cm.update_hotspot(
+                                self._session_id, path_arg, self._project_id
+                            )
+                        except Exception as _cm_exc:  # noqa: BLE001
+                            log.warning("ContinuousMemory update failed: %s", _cm_exc)
+
+                    # Post-write regression check
+                    if baseline is not None and self._regression_guard is not None:
+                        try:
+                            regression_result = self._regression_guard.verify_after_edit(
+                                _Path(pre_write_path)
+                            )
+                            if regression_result.new_failures:
+                                fix_note = self._enter_fix_loop(regression_result, path_arg)
+                                if fix_note:
+                                    result_content += f"\n\n{fix_note}"
+                        except Exception as _rg_exc:  # noqa: BLE001
+                            log.debug("regression verify failed: %s", _rg_exc)
+
+            # Build the tool result turn, marking write-tool results as non_droppable
+            # so the compressor never drops or truncates unverified file writes.
+            path_for_nd = args.get("path") or args.get("file_path") or "?"
+            tool_turn = Turn(
+                role="tool",
+                content=result_content,
+                tokens=count_tokens(result_content),
+                tool_name=tool_name,
+                tool_call_id=tool_call_id,
+                non_droppable=is_write,
+                non_droppable_reason=(
+                    f"unverified write: {path_for_nd}" if is_write else ""
+                ),
+            )
+            self._transcript.append(tool_turn)
+
+        self._budget.sync_from_transcript(self._transcript)
+
+    def _auto_quality(self, path_str: str) -> str:
+        """Run lint, type-check, security scan, and complexity check after a write.
+
+        Runs all applicable tools in parallel via ThreadPoolExecutor.
+        Returns a formatted warning string if issues are found, '' if all clean.
+        """
+        from pathlib import Path as _Path
+        from src.tools.quality_tools import (
+            ComplexityCheckTool, LintFileTool, SecurityScanTool, TypeCheckTool,
+        )
+
+        is_py = _Path(path_str).suffix.lower() == ".py"
+        is_security = any(p in path_str.lower() for p in _SECURITY_PATH_PATTERNS)
+
+        tasks: list[tuple[str, Any, dict[str, Any]]] = []
+        tasks.append(("lint", LintFileTool(), {"path": path_str}))
+        if is_py:
+            tasks.append(("typecheck", TypeCheckTool(), {"files": [path_str]}))
+        if is_security:
+            tasks.append(("security", SecurityScanTool(), {"path": path_str}))
+        tasks.append(("complexity", ComplexityCheckTool(), {"path": path_str}))
+
+        issues: list[str] = []
+        try:
+            with _cf.ThreadPoolExecutor(max_workers=len(tasks)) as pool:
+                futures = {
+                    pool.submit(tool.execute, params): label
+                    for label, tool, params in tasks
+                }
+                for future, label in futures.items():
+                    try:
+                        result = future.result(timeout=60)
+                        if label == "complexity":
+                            if result.output and "High complexity" in result.output:
+                                issues.append(f"Complexity: {result.output}")
+                        elif result.error:
+                            issues.append(f"{label.capitalize()}: {result.error}")
+                    except Exception as exc:  # noqa: BLE001
+                        log.debug("Quality tool %s raised: %s", label, exc)
+        except Exception as exc:  # noqa: BLE001
+            log.debug("_auto_quality pool failed for %s: %s", path_str, exc)
+            return ""
+
+        if not issues:
+            return ""
+        joined = "\n".join(issues)
+        return (
+            f"⚠ Auto-quality issues in {path_str}:\n{joined}\n"
+            "Fix these before marking the task complete."
+        )
+
+    def _auto_lint(self, path_str: str) -> str:
+        """Backward-compatible alias for _auto_quality."""
+        return self._auto_quality(path_str)
+
+    def _enter_fix_loop(self, regression_result: Any, file_path: str) -> str:
+        """Inject regression failure info into the transcript for the model to fix.
+
+        Returns a warning string to append to the tool result content.
+        If rollback is recommended (2+ consecutive failures), note that too.
+        """
+        failures = "\n".join(f"  ✗ {t}" for t in regression_result.new_failures)
+        msg_lines = [
+            f"⚠ Regression detected after editing {file_path}:",
+            failures,
+        ]
+        if regression_result.coverage_drop is not None:
+            msg_lines.append(
+                f"  Coverage dropped by {regression_result.coverage_drop:.1f}pp"
+            )
+        if regression_result.rollback_recommended:
+            msg_lines.append(
+                "  ⛔ Rollback recommended — 2+ consecutive failures on this file."
+                " Consider reverting your last edit."
+            )
+        else:
+            msg_lines.append(
+                "  Fix the failing tests before marking the task complete."
+            )
+        log.warning("Regression detected in %s: %s", file_path, regression_result.new_failures)
+        return "\n".join(msg_lines)
+
+    def _git_checkpoint_on_completion(self) -> None:
+        """Create a git checkpoint commit when a task completes naturally.
+
+        Called once at the end of a successful run(), not after each write.
+        Uses 'git add -A' — caller ensures this is safe (task completion context).
+        """
+        if self._git_wf is None or not self._files_written:
+            return
+        try:
+            files = ", ".join(str(p.name) for p in self._files_written[:3])
+            if len(self._files_written) > 3:
+                files += f" +{len(self._files_written) - 3} more"
+            self._git_wf.checkpoint(
+                f"task: wrote {files}",
+                turn_id=self._session_id,
+                files=list(self._files_written),
+            )
+            log.info("git: checkpoint commit after task completion")
+        except Exception as exc:  # noqa: BLE001
+            log.debug("Git checkpoint on completion skipped: %s", exc)
+
+    def _maybe_compress(self, turn_num: int = 0) -> int:
+        """Compress context when budget is high, using LLM digest if possible.
+
+        Triggered either by 5-turn cadence (every 5th turn) or when the budget
+        is near the limit (>= 80 %).  A re-compression guard prevents firing
+        twice within fewer than 5 turns.
+
+        Tries SessionCompressor first (smart LLM digest). Falls back to
+        simple eviction if compression fails or cfg has no API key.
+        Returns count of turns removed/replaced.
+        """
+        near_limit = self._budget.is_near_limit()
+        proactive = (turn_num % 5 == 0)
+        if not (near_limit or proactive):
+            return 0
+        # Re-compression guard: don't re-fire if we just compressed
+        if turn_num - self._last_compressed_at_turn < 5:
+            return 0
+        if not (near_limit or self._budget.needs_compression):
+            return 0
+
+        # Gather non-system turns available for compression (oldest half)
+        non_sys = [t for t in self._transcript._turns if t.role != "system"]
+        if len(non_sys) < 4:
+            # Not enough history to compress — just evict
+            evicted = self._transcript.maybe_evict()
+            self._budget.sync_from_transcript(self._transcript)
+            return evicted
+
+        half = max(2, len(non_sys) // 2)
+        candidates = non_sys[:half]
+        candidate_msgs = [t.to_compress_dict() for t in candidates]
+
+        try:
+            from src.memory.compressor import SessionCompressor
+            compressor = SessionCompressor(self._cfg)
+            result = compressor.compress(candidate_msgs, task_description="")
+            if result.digest and result.tokens_freed > 0:
+                # Remove the compressed turns by index (avoids id() reuse after GC)
+                all_turns = list(self._transcript._turns)
+                compressed_indices = frozenset(
+                    i for i, t in enumerate(all_turns) if t in candidates
+                )
+                remaining = [t for i, t in enumerate(all_turns) if i not in compressed_indices]
+                from collections import deque
+                self._transcript._turns = deque(remaining)
+                self._transcript._total_tokens = sum(
+                    t.tokens for t in self._transcript._turns
+                )
+                # Inject digest as a system-prefixed turn after the real system turn
+                digest_turn = Turn(
+                    role="system",
+                    content=result.digest,
+                    tokens=count_tokens(result.digest),
+                )
+                turns_list = list(self._transcript._turns)
+                insert_pos = 1 if (turns_list and turns_list[0].role == "system") else 0
+                turns_list.insert(insert_pos, digest_turn)
+                from collections import deque
+                self._transcript._turns = deque(turns_list)
+                self._transcript._total_tokens += digest_turn.tokens
+                self._budget.sync_from_transcript(self._transcript)
+                self._last_compressed_at_turn = turn_num
+                log.info(
+                    "Compressed %d turns into digest, freed ~%d tokens",
+                    result.turns_compressed, result.tokens_freed,
+                )
+                return result.turns_compressed
+        except Exception as exc:  # noqa: BLE001
+            log.warning("SessionCompressor failed, falling back to eviction: %s", exc)
+
+        # Fallback: simple eviction
+        evicted = self._transcript.maybe_evict()
+        self._budget.sync_from_transcript(self._transcript)
+        if evicted:
+            log.info("Evicted %d turns (fallback compression)", evicted)
+        return evicted
+
+    def _checkpoint(self) -> None:
+        """Submit a non-blocking checkpoint write to the background executor.
+
+        Takes a snapshot of non-system transcript turns and submits the DB
+        write to _CHECKPOINT_EXECUTOR (max_workers=1) so the agent thread is
+        never blocked.  Any pending (not-yet-started) future is cancelled
+        first — the newer snapshot supersedes it.
+
+        Silently no-ops if db or session_id are unavailable so tests without
+        a DB are unaffected.
+        """
+        if self._db is None or not self._session_id:
+            return
+        turns_snapshot = [
+            {
+                "role": t.role,
+                "content": t.content,
+                "tokens": t.tokens,
+                "tool_name": t.tool_name,
+                "tool_call_id": t.tool_call_id,
+                "tool_calls": t.tool_calls,
+            }
+            for t in self._transcript.to_turns()
+            if t.role != "system"  # system prompt is rebuilt on restore
+        ]
+        db = self._db
+        session_id = self._session_id
+
+        def _write() -> None:
+            try:
+                db.memory_save_turns(session_id, turns_snapshot)
+                log.debug(
+                    "Checkpointed %d turns for session %s",
+                    len(turns_snapshot), session_id,
+                )
+            except Exception as exc:  # noqa: BLE001
+                log.warning("Checkpoint failed (non-fatal): %s", exc)
+
+        # Cancel any pending (not-yet-started) future — newer snapshot wins
+        if self._checkpoint_future is not None and not self._checkpoint_future.done():
+            self._checkpoint_future.cancel()
+        self._checkpoint_future = _CHECKPOINT_EXECUTOR.submit(_write)
+        self._last_checkpoint_at = time.monotonic()
+
+    def _flush_checkpoint_sync(self, timeout: float = 10.0) -> None:
+        """Block until the pending async checkpoint write completes.
+
+        Call on clean exit and at all terminal run() returns to ensure the last
+        transcript snapshot is durable before the process moves on.
+        """
+        if self._checkpoint_future is not None:
+            try:
+                self._checkpoint_future.result(timeout=timeout)
+            except _cf.TimeoutError:
+                log.warning(
+                    "Checkpoint flush timed out after %.1fs — last snapshot may not persist",
+                    timeout,
+                )
+            except Exception as exc:  # noqa: BLE001
+                log.warning("Checkpoint flush error: %s", exc)
+            finally:
+                self._checkpoint_future = None
+
+    def restore_from_db(self, session_id: str | None = None) -> int:
+        """Reload checkpointed transcript turns from the DB.
+
+        Called on /resume to recover from a crash.  Replaces all non-system
+        turns in the transcript with the last saved checkpoint.
+
+        Args:
+            session_id: Optional session to restore from. Defaults to the
+                current ``self._session_id`` if not given.
+
+        Returns:
+            The number of turns reloaded; 0 if no checkpoint found.
+        """
+        target_session = session_id or self._session_id
+        if self._db is None or not target_session:
+            return 0
+        try:
+            # 24-hour staleness guard
+            sess_row = self._db.execute_one(
+                "SELECT updated_at FROM sessions WHERE session_id = ?",
+                (target_session,),
+            )
+            if sess_row and sess_row["updated_at"]:
+                from datetime import datetime, timedelta, timezone
+                try:
+                    updated_at = datetime.fromisoformat(
+                        str(sess_row["updated_at"]).replace("Z", "+00:00")
+                    )
+                    age = datetime.now(timezone.utc) - updated_at.astimezone(timezone.utc)
+                    if age > timedelta(hours=24):
+                        log.warning(
+                            "⚠ Session %s is over 24 hours old — context may be stale."
+                            " Continuing anyway.",
+                            target_session[:8],
+                        )
+                except (ValueError, AttributeError):
+                    pass
+
+            rows = self._db.memory_load_turns(target_session)
+            if not rows:
+                return 0
+            from collections import deque
+            system_turns = [t for t in self._transcript.to_turns() if t.role == "system"]
+            self._transcript._turns = deque(system_turns)
+            self._transcript._total_tokens = sum(t.tokens for t in system_turns)
+            for row in rows:
+                turn = Turn(
+                    role=row["role"],
+                    content=row.get("content") or "",
+                    tokens=row.get("tokens") or 0,
+                    tool_name=row.get("tool_name"),
+                    tool_call_id=row.get("tool_call_id"),
+                    tool_calls=row.get("tool_calls"),
+                )
+                self._transcript.append(turn)
+            self._budget.sync_from_transcript(self._transcript)
+            log.info(
+                "Restored %d turns from DB for session %s",
+                len(rows), target_session,
+            )
+            return len(rows)
+        except Exception as exc:  # noqa: BLE001
+            log.warning("restore_from_db failed (non-fatal): %s", exc)
+            return 0
+
+    def _event_log_begin(self, turn_num: int, user_message: str | None = None) -> str | None:
+        """Insert a session_events row for this turn; return event_id or None."""
+        if self._db is None or not self._session_id:
+            return None
+        try:
+            return self._db.event_log_begin_turn(
+                self._session_id,
+                self._model_turn_count,
+                self._model_id,
+                self._cfg.provider,
+                getattr(self._model, "tier", "coder"),
+                user_message=user_message,
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.debug("event_log_begin_turn: %s", exc)
+            return None
+
+    def _run_self_critique(
+        self, turn_num: int
+    ) -> Generator[AgentEvent, None, None]:
+        """Fire a cheap fast-reasoning self-critique before DONE is emitted.
+
+        Uses the Coder model (not Reasoner) to keep cost near zero.
+        The critique is surfaced as a THINKING event so the user can see it
+        in verbose mode without it cluttering the main output.
+        """
+        if not self._files_written:
+            return
+
+        file_list = ", ".join(str(p) for p in self._files_written[:5])
+        critique_prompt = (
+            f"You just modified: {file_list}.\n"
+            "Briefly critique the changes you made:\n"
+            "- Any logic errors or edge cases missed?\n"
+            "- Any security or correctness concerns?\n"
+            "- Is the code consistent with the surrounding style?\n"
+            "Be concise — 3–5 sentences max."
+        )
+        try:
+            response = self._gdm_client.complete(
+                [
+                    *self._transcript.to_messages()[-4:],
+                    {"role": "user", "content": critique_prompt},
+                ],
+                model=self._model_id,
+                max_tokens=300,
+            )
+            critique = (response.choices[0].message.content or "").strip()
+            if critique:
+                yield AgentEvent(EventType.THINKING, content=f"[self-critique] {critique}",
+                                 turn=turn_num)
+        except Exception as exc:  # noqa: BLE001
+            log.debug("Self-critique skipped: %s", exc)
+
+    def _maybe_review_gate(
+        self, turn_num: int
+    ) -> Generator[AgentEvent, None, None]:
+        """Auto-trigger ReviewGate if written files are security-sensitive."""
+        if not self._files_written:
+            return
+        try:
+            from src.agent.review_gate import ReviewGate, ReviewTrigger
+            trigger = ReviewTrigger()
+            if not trigger.should_review(self._files_written):
+                return
+            reason = trigger.classify(self._files_written)
+            gate = ReviewGate(cfg=self._cfg)
+            # Collect actual diff content (fixes empty-string bug)
+            from src.agent.review_gate import _collect_diff
+            actual_diff = _collect_diff(
+                self._files_written, self._cfg.project_root
+            ) or "(diff unavailable)"
+            gate_result = gate.review(
+                files_changed=self._files_written,
+                diff_text=actual_diff,
+                trigger_reason=reason,
+            )
+            if gate_result.blocks_merge:
+                findings_text = "\n".join(
+                    f"- [{f.severity.value.upper()}] {f.message}"
+                    for f in gate_result.report.findings
+                )
+                yield AgentEvent(
+                    EventType.THINKING,
+                    content=f"[review-gate] ⚠ Review flagged issues:\n{findings_text}",
+                    turn=turn_num,
+                )
+            else:
+                yield AgentEvent(
+                    EventType.THINKING,
+                    content=f"[review-gate] ✅ Review passed ({reason})",
+                    turn=turn_num,
+                )
+        except Exception as exc:  # noqa: BLE001
+            log.debug("ReviewGate skipped: %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# Autonomy audit log (module-level for testability)
+# ---------------------------------------------------------------------------
+
+
+def write_autonomy_audit(
+    db_conn: Any,
+    session_id: str,
+    level: int,
+    action: str,
+    details: dict,  # type: ignore[type-arg]
+    checkpoint_id: str | None = None,
+) -> None:
+    """Write an audit entry for L3+ autonomy actions.
+
+    Silently skips levels below 3 — no-op by design.
+    """
+    if level < 3:
+        return
+    import json
+    import time
+
+    db_conn.execute(
+        "CREATE TABLE IF NOT EXISTS autonomy_audit "
+        "(session_id TEXT, timestamp REAL, level INTEGER, action TEXT, details TEXT, checkpoint_id TEXT)",
+    )
+    db_conn.execute(
+        "INSERT INTO autonomy_audit "
+        "(session_id, timestamp, level, action, details, checkpoint_id) VALUES (?,?,?,?,?,?)",
+        (session_id, time.time(), level, action, json.dumps(details), checkpoint_id),
+    )
+    db_conn.commit()
+