hexcli 2.8.0__py3-none-any.whl

hexcli/local_escalation.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""hexcli.local_escalation — consult a bigger LOCAL model at hard moments.
+
+docs/V2_PLAN.md §4 escalation ladder, de-risked: instead of the (unavailable)
+Qwen3-4B-Thinking-2507 self-compile, the precompiled qualcomm Qwen3-8B bundle
+serves as the "senior engineer" — a hybrid-thinking model whose ~8-9 tok/s
+decode is fine for rare consultations even though it would be too slow as the
+main loop. Fully offline; the cloud path (hexcli.escalate) remains a separate,
+opt-in, last resort.
+
+The measured failure modes this targets (2026-07-30 instrument data):
+  * loop-detector trips (model repeats a failing call and cannot adapt)
+  * verification-gate nudges being ignored (finishes without checking work)
+  * "prose instead of action" — the model narrates or gives up on an edit
+    request without ever mutating a file (uc1-t5/t6, 0/3)
+
+Design: one consult per turn max; every failure path degrades to the previous
+behaviour (never crash the loop); the escalation server is spawned lazily on
+first use and reused for the session.
+"""
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import re
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+DETACHED_PROCESS = 0x00000008
+
+_ESCALATION_SYSTEM = (
+    "You are a senior software engineer advising a junior terminal agent that "
+    "has gotten stuck. Think through the situation carefully, then give ONE "
+    "concrete, specific next action: the exact command to run, the exact "
+    "old/new text for a file edit, or the exact question to ask. Be brief and "
+    "actionable — the junior agent will execute your advice literally."
+)
+
+# Verbs that signal the user asked for a file mutation; used by the
+# prose-instead-of-action trigger.
+_EDIT_INTENT_RE = re.compile(
+    r"\b(add|fix|edit|update|change|modify|refactor|rename|insert|remove|"
+    r"delete|guard|implement|patch|rewrite|append)\b", re.IGNORECASE)
+_MUTATING_TOOLS = frozenset({"edit_file", "write_file", "append_file", "edit", "write"})
+
+
+def looks_like_edit_request(query: str) -> bool:
+    return bool(_EDIT_INTENT_RE.search(query or ""))
+
+
+def turn_mutated(tools_used: list[str]) -> bool:
+    return any(t in _MUTATING_TOOLS for t in tools_used)
+
+
+class LocalEscalator:
+    """Lazily-started second npurun server hosting the escalation model."""
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        self.model = str(config.get("escalation_local_model", "") or "")
+        self.bind = str(config.get("escalation_local_bind", "127.0.0.1:11436"))
+        self.max_tokens = int(config.get("escalation_max_output_tokens", 900))
+        self.timeout_s = int(config.get("escalation_timeout_seconds", 240))
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._failed = False
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.model) and not self._failed
+
+    # -- server lifecycle ---------------------------------------------------
+
+    def _npurun_exe(self) -> Path:
+        return Path.home() / ".cargo" / "bin" / "npurun.exe"
+
+    def _env(self) -> dict[str, str]:
+        env = os.environ.copy()
+        sdk = Path(env.get("QNN_SDK_ROOT", r"C:\Qualcomm\AIStack\QAIRT_2.47.0"))
+        env["QNN_SDK_ROOT"] = str(sdk)
+        env["ADSP_LIBRARY_PATH"] = str(sdk / "lib" / "hexagon-v73" / "unsigned")
+        env["PATH"] = (
+            f"{sdk / 'bin' / 'aarch64-windows-msvc'};"
+            f"{sdk / 'lib' / 'aarch64-windows-msvc'};"
+            f"{self._npurun_exe().parent};{env.get('PATH', '')}"
+        )
+        return env
+
+    def _healthy(self) -> bool:
+        try:
+            with urllib.request.urlopen(f"http://{self.bind}/healthz", timeout=3) as r:
+                return r.status == 200
+        except Exception:
+            return False
+
+    def ensure_server(self, wait_s: int = 90) -> bool:
+        """Start the escalation server if it isn't already up. Slow on first
+        use (bundle load ~10s + spawn); a no-op afterwards."""
+        if self._healthy():
+            return True
+        exe = self._npurun_exe()
+        if not exe.exists():
+            self._failed = True
+            return False
+        try:
+            self._proc = subprocess.Popen(
+                [str(exe), "serve", "--model", self.model, "--bind", self.bind],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                env=self._env(), creationflags=DETACHED_PROCESS,
+            )
+            # DETACHED_PROCESS means this multi-GB server outlives the CLI
+            # unless someone reaps it — and nothing called stop(). Register
+            # now, at the moment of spawn, so no exit path can miss it.
+            atexit.register(self.stop)
+        except Exception:
+            self._failed = True
+            return False
+        deadline = time.time() + wait_s
+        while time.time() < deadline:
+            if self._healthy():
+                return True
+            time.sleep(2)
+        self._failed = True  # don't retry every turn against a broken spawn
+        return False
+
+    def stop(self) -> None:
+        """Reap the escalation server. Idempotent; safe from atexit."""
+        proc, self._proc = self._proc, None
+        if proc is None:
+            return
+        try:
+            subprocess.run(["taskkill", "/T", "/F", "/PID", str(proc.pid)],
+                           capture_output=True, timeout=10)
+        except Exception:
+            try:
+                proc.kill()
+            except Exception:
+                pass
+
+    # -- consultation -------------------------------------------------------
+
+    def consult(self, situation: str) -> str | None:
+        """Ask the escalation model for advice. Returns None on ANY failure —
+        callers must degrade gracefully."""
+        if not self.enabled or not self.ensure_server():
+            return None
+        body = json.dumps({
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": _ESCALATION_SYSTEM},
+                {"role": "user", "content": situation},
+            ],
+            "max_tokens": self.max_tokens,
+            "temperature": 0.6,
+            "stream": False,
+            "stop": ["<|im_end|>", "<|im_start|>"],
+        }).encode()
+        req = urllib.request.Request(
+            f"http://{self.bind}/v1/chat/completions",
+            data=body, headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout_s) as resp:
+                data = json.loads(resp.read())
+            text = data["choices"][0]["message"]["content"] or ""
+        except Exception:
+            return None
+        # The hybrid 8B thinks in <think> blocks; only the conclusion goes
+        # back to the 4B loop.
+        text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL).strip()
+        return text or None
+
+
+def build_situation(
+    query: str,
+    recent_events: list[str],
+    problem: str,
+    max_chars: int = 4000,
+) -> str:
+    """Compact consultation prompt: the task, what happened, what went wrong."""
+    events = "\n".join(f"- {e[:400]}" for e in recent_events[-8:])
+    text = (
+        f"TASK the agent was given:\n{query}\n\n"
+        f"RECENT ACTIONS AND RESULTS:\n{events}\n\n"
+        f"PROBLEM:\n{problem}\n\n"
+        "What exactly should the agent do next?"
+    )
+    return text[:max_chars]

hexcli/lockfile.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""hexcli.lockfile — Advisory PID-file process lock for the shellai entry point.
+
+Prevents two shellai instances from sharing the same npurun backend at the
+same time (the backend is a singleton: one KV-cache context, one CDSP
+session). All operations are non-fatal: if the filesystem is read-only or
+ctypes is unavailable, the lock is silently skipped and the agent still
+starts.
+"""
+from __future__ import annotations
+
+import atexit
+import ctypes
+import os
+from pathlib import Path
+
+_LOCK_PATH: Path | None = None
+_SYNCHRONIZE = 0x00100000  # Windows PROCESS_SYNCHRONIZE access right
+
+
+def _pid_alive(pid: int) -> bool:
+    """Return True if the process with this PID is currently running (Windows)."""
+    try:
+        h = ctypes.windll.kernel32.OpenProcess(_SYNCHRONIZE, False, pid)
+        if h:
+            ctypes.windll.kernel32.CloseHandle(h)
+            return True
+        return False
+    except Exception:
+        return False
+
+
+def acquire(lock_dir: Path) -> str | None:
+    """Write a PID lock file in lock_dir.
+
+    Returns a warning string if another live shellai process is already
+    running; returns None if the lock was acquired cleanly (or if the
+    check could not be performed).
+    """
+    global _LOCK_PATH
+    lock_path = lock_dir / "shellai.lock"
+    _LOCK_PATH = lock_path
+    warning: str | None = None
+
+    if lock_path.exists():
+        try:
+            existing_pid = int(lock_path.read_text(encoding="utf-8").strip())
+            if existing_pid != os.getpid() and _pid_alive(existing_pid):
+                warning = f"  ⚠ Another Hex CLI is running in this directory, PID {existing_pid}."
+        except Exception:
+            pass  # stale or unreadable lock — overwrite silently
+
+    try:
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        lock_path.write_text(str(os.getpid()), encoding="utf-8")
+        atexit.register(_release)
+    except Exception:
+        pass  # read-only filesystem or permission error — advisory only
+
+    return warning
+
+
+def _release() -> None:
+    """Remove the lock file if it still contains our PID."""
+    if _LOCK_PATH is None or not _LOCK_PATH.exists():
+        return
+    try:
+        if int(_LOCK_PATH.read_text(encoding="utf-8").strip()) == os.getpid():
+            _LOCK_PATH.unlink()
+    except Exception:
+        pass

hexcli/loop_v2.py

@@ -0,0 +1,393 @@
+#!/usr/bin/env python3
+"""hexcli.loop_v2 — the v2 agent loop (docs/V2_PLAN.md §5-§6).
+
+Selected via config {"protocol": "v2"}; hexcli.agent.run_autopilot delegates
+here so the v1 loop stays untouched while v2 is A/B-tested on the eval
+instrument. Differences from v1, by design:
+
+  * Byte-stable system core (protocol_v2.SYSTEM_PROMPT_V2) + one per-session
+    context line — no per-turn workspace snapshot, no date/cwd churn, no
+    keyword-conditional tool schemas. Append-only message layout.
+  * Native-format actions parsed by protocol_v2; multi-line payloads never
+    touch JSON. A plain-text reply IS the final answer.
+  * Unconditional retry-with-precise-error-feedback on malformed output
+    (v1 retried only when the raw text happened to contain a tool name).
+  * Persistent PowerShell session: cd/env/variables survive across steps
+    (and across turns in the REPL).
+  * Fuzzy error-loop detection on (tool, args, payload) — near-identical
+    failing calls trip it, not just byte-identical (tool, output) pairs.
+
+Shares with v1: call_llm transport (mock backend included), safety
+classification + audit log + destructive confirm, sensitive-path blocks,
+undo snapshots, memory indexing, telemetry, and the AutopilotProbe seam —
+so the eval instrument drives both protocols unchanged.
+"""
+from __future__ import annotations
+
+import atexit
+import hashlib
+import json
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from . import memory, safety, telemetry, ui
+from .protocol_v2 import (
+    SYSTEM_PROMPT_V2,
+    apply_search_replace,
+    build_session_context,
+    parse_response,
+    render_tool_result,
+)
+from .shell_session import ShellSession
+
+
+def trim_middle(text: str, limit: int) -> str:
+    """Head+tail truncation: command output usually carries its verdict at the
+    END (exit summaries, stack traces), so the tail must survive — v1's
+    head-only trim hid exactly the informative part."""
+    if len(text) <= limit:
+        return text
+    head = int(limit * 0.6)
+    tail = limit - head
+    omitted = len(text) - head - tail
+    return (text[:head] + f"\n[... {omitted} chars omitted ...]\n" + text[-tail:])
+
+
+_MAX_FORMAT_RETRIES = 2       # per step, mirrors v1's retry budget
+_LOOP_WINDOW = 3              # near-identical calls before the loop detector trips
+_READ_DEFAULT_LIMIT = 400     # lines per read page
+
+# Persistent shells for REPL sessions, keyed by session id. One-shot and eval
+# runs (session=None) get an ephemeral shell that lives for the turn only.
+_SESSION_SHELLS: dict[str, ShellSession] = {}
+
+
+@atexit.register
+def _close_all_shells() -> None:
+    for sh in list(_SESSION_SHELLS.values()):
+        try:
+            sh.close()
+        except Exception:
+            pass
+    _SESSION_SHELLS.clear()
+
+
+def _get_shell(session: dict[str, Any] | None, cwd: str,
+               shell_exe: str = "") -> tuple[ShellSession, bool]:
+    # Honour the user's shell_exe (and v1's pwsh-over-powershell preference);
+    # v2 previously hardcoded powershell.exe and silently ignored the setting.
+    exe = shell_exe or "powershell.exe"
+    if session and session.get("id"):
+        sid = str(session["id"])
+        sh = _SESSION_SHELLS.get(sid)
+        if sh is None:
+            sh = ShellSession(cwd=cwd, shell_exe=exe)
+            _SESSION_SHELLS[sid] = sh
+        return sh, False
+    return ShellSession(cwd=cwd, shell_exe=exe), True
+
+
+def close_session_shell(session_id: str) -> None:
+    sh = _SESSION_SHELLS.pop(session_id, None)
+    if sh is not None:
+        sh.close()
+
+
+# ---------------------------------------------------------------------------
+# v2 tool dispatch
+# ---------------------------------------------------------------------------
+
+def _tool_read(agent: Any, args: dict[str, Any], output_limit: int) -> str:
+    path_text = str(args.get("path") or "").strip()
+    if not path_text:
+        return "Error: read requires 'path'."
+    path = agent.resolve_path(path_text)
+    agent._check_sensitive_path(path, "read")
+    if not path.exists():
+        return f"Error: {path} does not exist."
+    if path.is_dir():
+        # The 4B model habitually tries read(".") to list a directory; a raw
+        # PermissionError here reads as "access denied" and derails the task.
+        return (f"Error: {path} is a directory, not a file. To list its "
+                f"contents, use shell with: Get-ChildItem \"{path}\"")
+    lines = path.read_text(encoding="utf-8", errors="replace").split("\n")
+    total = len(lines)
+    offset = max(1, int(args.get("offset") or 1))
+    limit = max(1, int(args.get("limit") or _READ_DEFAULT_LIMIT))
+    page = lines[offset - 1:offset - 1 + limit]
+    body = "\n".join(page)
+    header = ""
+    if offset > 1 or offset - 1 + limit < total:
+        end = min(offset - 1 + len(page), total)
+        header = (f"[lines {offset}-{end} of {total}; use offset/limit to read more]\n")
+    ui.tool_event("read", f"{path} ({total} lines)")
+    return header + agent.trim_text(body, output_limit)
+
+
+def _tool_write(agent: Any, args: dict[str, Any], payload: str | None) -> str:
+    path_text = str(args.get("path") or "").strip()
+    if not path_text:
+        return "Error: write requires 'path'."
+    if payload is None:
+        return "Error: write requires its file content in a fenced block after </action>."
+    return agent.write_file_tool(path_text, payload)
+
+
+def _tool_edit(agent: Any, args: dict[str, Any], payload: list[tuple[str, str]] | None) -> str:
+    path_text = str(args.get("path") or "").strip()
+    if not path_text:
+        return "Error: edit requires 'path'."
+    if not payload:
+        return "Error: edit requires at least one SEARCH/REPLACE block after </action>."
+    path = agent.resolve_path(path_text)
+    # This block reimplements the edit (payload blocks instead of old/new
+    # strings) rather than delegating, so it must gate itself. The write-scope
+    # half was once missing here while v1 had it, letting protocol v2 edit
+    # anywhere on disk — hence the single guard_mutation entry point.
+    agent.guard_mutation(path, "edit", agent._ACTIVE_CONFIG)
+    if not path.exists():
+        return f"Error: {path} does not exist. Use write to create new files."
+    content = path.read_text(encoding="utf-8", errors="replace")
+    new_content, err = apply_search_replace(content, payload)
+    if err:
+        return f"Error: {err}"
+    tmp = path.parent / (path.name + ".tmp")
+    tmp.write_text(new_content, encoding="utf-8")
+    tmp.replace(path)
+    ui.tool_event("edit", f"{path} ({len(payload)} block(s))")
+    return f"Edited {path}: {len(payload)} block(s) applied."
+
+
+def _tool_shell(agent: Any, config: dict[str, Any], sh: ShellSession, args: dict[str, Any]) -> str:
+    cmd = str(args.get("command") or "").strip()
+    if not cmd:
+        return "Error: shell requires 'command'."
+    classification = safety.classify_command(cmd)
+    if classification == "destructive" and config.get("autopilot_confirm_destructive", True):
+        if not ui.confirm_destructive_command(cmd):
+            safety.append_audit_log(agent._CURRENT_SESSION_ID, classification, cmd, "blocked")
+            return "Blocked by user."
+    if classification == "sensitive" and config.get("autopilot_confirm_sensitive", True):
+        if not ui.confirm_sensitive_command(cmd):
+            safety.append_audit_log(agent._CURRENT_SESSION_ID, classification, cmd, "blocked")
+            return ("Blocked: this command accesses sensitive data (credentials, keys, "
+                    "or security files) and was not confirmed. Explain to the user what "
+                    "you wanted and why, instead of retrying.")
+    ui.command_echo(cmd)
+    result = sh.run(cmd, timeout_s=int(config.get("timeout_seconds", 300)))
+    safety.append_audit_log(agent._CURRENT_SESSION_ID, classification, cmd, result.get("exit_code"))
+    code = result.get("exit_code")
+    prefix = f"Exit code: {code}\n" if code is not None else ""
+    return prefix + (result.get("output") or "").strip()
+
+
+def _dispatch(agent: Any, config: dict[str, Any], sh: ShellSession, parsed: Any,
+              shell_exe: str, output_limit: int) -> str:
+    tool, args, payload = parsed.tool, parsed.args, parsed.payload
+    try:
+        if tool == "shell":
+            return _tool_shell(agent, config, sh, args)
+        if tool == "read":
+            return _tool_read(agent, args, output_limit)
+        if tool == "write":
+            return _tool_write(agent, args, payload)
+        if tool == "edit":
+            return _tool_edit(agent, args, payload)
+        if tool == "grep":
+            action = {"action": "tool", "tool": "search_files",
+                      "args": {"pattern": args.get("pattern", ""), "path": args.get("path", ".")}}
+            return agent.execute_tool_call(config, action, shell_exe)
+        if tool in ("recall", "fetch_url"):
+            v1_name = "search_memory" if tool == "recall" else tool
+            action = {"action": "tool", "tool": v1_name, "args": dict(args)}
+            return agent.execute_tool_call(config, action, shell_exe)
+    except agent.UserCancelled:
+        raise
+    except Exception as exc:  # noqa: BLE001 — tool failures feed back to the model
+        return f"Error: {exc}"
+    return f"Error: unknown tool {tool!r}."
+
+
+def _call_signature(parsed: Any) -> str:
+    payload_repr = ""
+    if parsed.payload is not None:
+        payload_repr = hashlib.sha1(repr(parsed.payload).encode()).hexdigest()[:12]
+    return f"{parsed.tool}|{json.dumps(parsed.args, sort_keys=True)}|{payload_repr}"
+
+
+# ---------------------------------------------------------------------------
+# The loop
+# ---------------------------------------------------------------------------
+
+def run(
+    config: dict[str, Any],
+    history: list[dict[str, str]],
+    query: str,
+    shell_exe: str,
+    session: dict[str, Any] | None = None,
+    turn: telemetry.TurnRecorder | None = None,
+    probe: Any = None,
+) -> str:
+    import hexcli.agent as agent  # late import; agent imports us lazily too
+
+    agent.set_active_config(config)
+    cwd = str(Path.cwd())
+    max_steps = int(config.get("max_agent_steps", 15))
+    output_limit = int(config.get("tool_output_limit", 12000))
+
+    system_prompt = (
+        SYSTEM_PROMPT_V2
+        + "\n\n"
+        + build_session_context(cwd, datetime.now().strftime("%Y-%m-%d"))
+    )
+    messages: list[dict[str, str]] = [
+        {"role": "system", "content": system_prompt},
+        *history,
+        {"role": "user", "content": query.strip()},
+    ]
+    agent._probe(probe, "on_start", system_prompt, [dict(m) for m in messages])
+
+    sh, ephemeral_shell = _get_shell(session, cwd, shell_exe)
+    tools_used: list[str] = []
+    touched_paths: list[str] = []
+    turn_snapshots: dict[str, str | None] = {}
+    recent_sigs: list[tuple[str, bool]] = []  # (signature, was_error)
+    last_tool_output = ""
+    # Verification-gated finish (docs/V2_PLAN.md §5.3): after a successful file
+    # mutation, the model must observe SOMETHING (run/read/check) before its
+    # final answer is accepted. One nudge max — the gate guides, never traps.
+    unverified_mutation = False
+    verify_nudge_used = False
+
+    def _finish(kind: str, message: str, outcome: str) -> str:
+        memory.maybe_index_turn(config, query, tools_used, touched_paths, outcome=outcome)
+        if session:
+            agent._record_undo_snapshots(session, turn_snapshots)
+        if ephemeral_shell:
+            sh.close()
+        agent._probe(probe, "on_end", kind, message)
+        return message
+
+    try:
+        for step in range(max_steps):
+            step_label = "thinking" if step == 0 else f"step {step + 1}/{max_steps}"
+            if sys.stderr.isatty():
+                agent.cprint(f"\n  {step_label}...", agent.C.DIM, file=sys.stderr)
+
+            parsed = None
+            raw = ""
+            for attempt in range(_MAX_FORMAT_RETRIES + 1):
+                llm_start = time.monotonic()
+                raw, eval_count = agent.call_llm(
+                    config, messages, "autopilot_max_output_tokens",
+                    label=step_label, json_format=False,
+                )
+                llm_latency = time.monotonic() - llm_start
+                if turn:
+                    turn.record_llm(llm_latency, eval_count)
+                agent._probe(probe, "on_llm", step, attempt, raw, llm_latency)
+                parsed = parse_response(raw)
+                if parsed.kind != "malformed":
+                    break
+                if attempt < _MAX_FORMAT_RETRIES:
+                    messages.append({"role": "assistant", "content": agent.strip_thinking(raw)})
+                    messages.append({"role": "user", "content": f"Format error: {parsed.error}"})
+            assert parsed is not None
+
+            if parsed.kind == "malformed":
+                # Retries exhausted — report truthfully instead of pretending.
+                return _finish(
+                    "malformed",
+                    f"I could not produce a valid action ({parsed.error}). "
+                    f"Last tool output, if any, follows:\n{last_tool_output}".strip(),
+                    "malformed",
+                )
+
+            if parsed.kind == "final":
+                if (unverified_mutation and not verify_nudge_used
+                        and config.get("require_verification", True)):
+                    verify_nudge_used = True
+                    messages.append({"role": "assistant", "content": agent.strip_thinking(raw)})
+                    changed = touched_paths[-1] if touched_paths else "the file"
+                    messages.append({
+                        "role": "user",
+                        "content": (
+                            f"You modified {changed} but never verified the result. "
+                            f"Use the read tool on {changed} (or run it via shell if "
+                            "it is code) to confirm the change, then report what you "
+                            "actually observed."
+                        ),
+                    })
+                    continue
+                return _finish("finish", parsed.final_text, "completed")
+
+            # Tool action.
+            tool = parsed.tool
+            tools_used.append(tool)
+            tool_path = parsed.args.get("path") if isinstance(parsed.args, dict) else None
+            if tool_path:
+                touched_paths.append(str(tool_path))
+            if tool in ("write", "edit") and tool_path:
+                try:
+                    snap_key = str(agent.resolve_path(str(tool_path)))
+                    if snap_key not in turn_snapshots:
+                        p = Path(snap_key)
+                        turn_snapshots[snap_key] = (
+                            p.read_text(encoding="utf-8") if p.exists() else None
+                        )
+                except Exception:
+                    pass
+
+            ui.tool_header(tool)
+            tool_start = time.monotonic()
+            tool_output = _dispatch(agent, config, sh, parsed, shell_exe, output_limit)
+            tool_latency = time.monotonic() - tool_start
+            tool_status = "error" if tool_output.startswith("Error:") else "ok"
+            if turn:
+                turn.record_tool(tool, parsed.args, tool_latency, tool_status)
+            agent._probe(probe, "on_tool", step, tool, dict(parsed.args or {}),
+                         tool_output, tool_latency, tool_status)
+            last_tool_output = tool_output
+
+            if tool in ("write", "edit") and tool_status == "ok":
+                unverified_mutation = True
+            elif tool in ("shell", "read") and tool_status == "ok":
+                # Any successful observation after the mutation counts as
+                # verification — the model saw real post-change state.
+                unverified_mutation = False
+
+            # Fuzzy loop detection: N consecutive near-identical calls, at
+            # least one of which errored, means the agent is spinning.
+            sig = _call_signature(parsed)
+            recent_sigs.append((sig, tool_status == "error"))
+            if len(recent_sigs) > _LOOP_WINDOW:
+                recent_sigs.pop(0)
+            if (len(recent_sigs) == _LOOP_WINDOW
+                    and len({s for s, _ in recent_sigs}) == 1
+                    and any(err for _, err in recent_sigs)):
+                agent.cprint(
+                    f"\n  ⚠ Agent repeated the same failing call {_LOOP_WINDOW}x. Stopping.",
+                    agent.C.BYELLOW,
+                )
+                return _finish(
+                    "loop_stop",
+                    f"I kept repeating the same failing action and stopped. Last error:\n{tool_output}",
+                    "error_loop",
+                )
+
+            messages.append({"role": "assistant", "content": agent.strip_thinking(raw)})
+            messages.append({
+                "role": "user",
+                "content": render_tool_result(tool, trim_middle(tool_output, output_limit)),
+            })
+
+        return _finish("step_limit", last_tool_output or "Hit the step limit without finishing.", "step_limit")
+    except (agent.UserCancelled, KeyboardInterrupt):
+        if session:
+            agent._record_undo_snapshots(session, turn_snapshots)
+        if ephemeral_shell:
+            sh.close()
+        raise