drydock-cli 2.7.6__tar.gz → 2.7.22__tar.gz

drydock_cli-2.7.22/.auto_release.lock

@@ -0,0 +1 @@
+522842

drydock_cli-2.7.22/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"facd51cc-fa47-4911-afc8-14485ae9caf3","pid":711220,"acquiredAt":1775966390914}

{drydock_cli-2.7.6 → drydock_cli-2.7.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.7.6
+Version: 2.7.22
 Summary: Local-first CLI coding agent — tested with Gemma 4 26B via vLLM
 Project-URL: Homepage, https://github.com/fbobe321/drydock
 Project-URL: Repository, https://github.com/fbobe321/drydock

{drydock_cli-2.7.6 → drydock_cli-2.7.22}/PRD.md

@@ -1,7 +1,7 @@
 # DryDock — Local CLI Coding Agent
 
 **Repository:** https://github.com/fbobe321/drydock
-**PyPI:** https://pypi.org/project/drydock-cli/ (v2.7.4)
+**PyPI:** https://pypi.org/project/drydock-cli/ (v2.7.6)
 **License:** Apache 2.0 (fork of [mistralai/mistral-vibe](https://github.com/mistralai/mistral-vibe))
 
 ## Vision
@@ -398,6 +398,54 @@ order:
 Auto-created if none exist. AGENTS.md is essential for devstral
 (it loops without one) but Gemma 4 works without it.
 
+## Recent fixes (April 25, 2026)
+
+### v2.7.6 (April 25, 09:18 CDT) — truncation JSON-validity fix
+**Root cause of the recurring vLLM 400 spiral.** Live capture from a
+2000-prompt stress run pinpointed it: `_truncate_old_tool_results` was
+shrinking old assistant `tool_calls.function.arguments` by appending
+`"\n[…truncated N bytes…]"` directly into the JSON-string field. vLLM's
+tool-call parser re-parses arguments as JSON; raw `\n` (0x0A) inside a
+JSON string is invalid → `JSONDecodeError: Invalid control character
+at: line 1 column 401` → HTTP 400 → drydock's "6 consecutive errors"
+banner → harness `/clear` → prompt lost. The pattern repeated every
+~30 prompts as truncation kicked in, costing dozens of prompts per
+batch.
+
+Fix in `agent_loop.py::_truncate_old_tool_results`: rebuild the
+truncated arguments as a small VALID JSON stub (`{"_truncated": true,
+"_original_bytes": N, "<id_field>": ...}`) preserving the most-useful
+identifying field (path / file_path / command / cmd / url / file)
+from the parsed original. 5 regression tests in
+`tests/test_truncate_args_valid_json.py`; 2 of them fail with the
+exact "char 400" error without the fix.
+
+**Stress measurement:** before fix, write rate 10% / vLLM 400s
+315 per 30 min. After fix, write rate sustained at ~44% / vLLM 400s
+0 per hour. **4.4× correctness improvement** on the same workload.
+
+### v2.7.6 (April 25) — search_replace APPEND fallback
+The 2026-04-25 stress run also exposed a search_replace REFUSED loop:
+Gemma 4 sent a single new function with no SEARCH/REPLACE markers,
+the safety check refused as "would shrink the file by 90%", model
+retried the same broken call, prompts dropped. Model intent in this
+shape is APPEND, not rewrite.
+
+Fix in `search_replace.py`: try appending the raw content first; for
+.py files only commit if the combined text still parses cleanly; if
+syntax breaks, return a directive REFUSED that explains the
+EOF-anchored SEARCH/REPLACE pattern. Tests in
+`tests/tools/test_search_replace_append_fallback.py`.
+
+### v2.7.5 (April 25, 07:25 CDT) — yesterday's GitHub issue batch
+Auto-release shipped the four fixes from 2026-04-24 plus the PRD
+refresh:
+- #13 control-char JSON sanitization in OpenAIAdapter
+- #11 fake `task(...)` text nuker in format.py
+- #12 wall-rescue at stream end in messages.py
+- #10 navygpt auto-disable in tool manager
+- PRD.md refresh for v2.7.4 (Admiral, Meta-Harness sections)
+
 ## Recent fixes (April 16–24, 2026)
 
 ### v2.7.4 + unreleased (April 24) — GitHub issue triage batch
@@ -749,7 +797,16 @@ Second claude-code pass produced two more wins:
 
 ## Roadmap
 
-### Currently in flight (April 24, 2026)
+### Currently in flight (April 25, 2026)
+- **2000-prompt stress test** running against v2.7.6 on
+  `/data3/drydock_test_projects/403_tool_agent` (PID 3713698, log
+  `/tmp/stress_2000_1777119799.log`). At 5+ hours in: 189/1658 prompts
+  done, write rate ~44% sustained, vLLM 400s eliminated, SKIPs 8%.
+  Babysitter cron will auto-restart on death.
+- **Resume sentinel** at `/data3/drydock/resume.md` — point a fresh
+  Claude session at it via `review the resume.md file and continue`.
+
+### Carried over from April 24, 2026
 - **GitHub issue triage** — 4 user-reported bugs (#10–#13) fixed this
   week, all with regression tests. Remaining open issues should be
   picked up on sight; `feedback_proactive_github_issues.md` codifies

{drydock_cli-2.7.6 → drydock_cli-2.7.22}/drydock/admiral/detectors.py

@@ -80,18 +80,36 @@ def detect_struggle(messages: Sequence[LLMMessage], threshold: int = 20) -> Find
                 calls_since_write += 1
     if calls_since_write < threshold:
         return None
-    hint = (
-        "Either (a) you already have enough context — commit to a plan and "
-        "start writing code now, or (b) you're genuinely stuck — stop and "
-        "report what's blocking you to the user."
-    )
-    return Finding(
-        code=f"struggle:{calls_since_write}:{last_write_tool or 'none'}",
-        directive=(
+    # Stable code (no count) so DEDUP_WINDOW_SEC suppresses repeated firings.
+    # Previously included the count, which caused 33 identical interventions
+    # in a single session (each with a unique key that bypassed dedup).
+    code = f"struggle:{last_write_tool or 'none'}"
+    if calls_since_write >= 30:
+        if last_write_tool is None:
+            directive = (
+                f"Admiral: you have made {calls_since_write} tool calls without "
+                f"writing a single file. You have enough context. STOP exploring "
+                f"and start writing code NOW. Call `write_file` to create your "
+                f"first file immediately."
+            )
+        else:
+            directive = (
+                f"Admiral: you have made {calls_since_write} tool calls without "
+                f"writing any file — search_replace is clearly not finding the text. "
+                f"STOP retrying. Call `write_file` with `overwrite=True` to rewrite "
+                f"the target file from scratch right now."
+            )
+    else:
+        hint = (
+            "Either (a) you already have enough context — commit to a plan and "
+            "start writing code now, or (b) you're genuinely stuck — stop and "
+            "report what's blocking you to the user."
+        )
+        directive = (
             f"Admiral: you have made {calls_since_write} tool calls without "
             f"writing or editing any file. {hint}"
-        ),
-    )
+        )
+    return Finding(code=code, directive=directive)
 
 
 def run_all(messages: Sequence[LLMMessage]) -> list[Finding]:

{drydock_cli-2.7.6 → drydock_cli-2.7.22}/drydock/admiral/detectors_proposed.py

@@ -43,11 +43,18 @@ def _tool_result_errored(m: LLMMessage) -> bool:
     """Heuristic: does this tool-role message look like a failure?
 
     Conservative — we only want high-precision firing on actual errors.
-    Scanned the first 800 chars of the result content.
+    Scanned the first 200 chars of the result content (tightened from 800
+    to avoid false positives when matched file content contains words like
+    "error" or "failed" — grep results starting with "matches:" are always
+    successful).
     """
     if m.role is not Role.tool:
         return False
-    content = str(getattr(m, "content", "") or "")[:800].lower()
+    raw = str(getattr(m, "content", "") or "")
+    # Successful grep results start with "matches:" — never treat as error.
+    if raw.lstrip().startswith("matches:"):
+        return False
+    content = raw[:200].lower()
     return any(marker in content for marker in _TOOL_ERROR_MARKERS)
 
 

{drydock_cli-2.7.6 → drydock_cli-2.7.22}/drydock/core/agent_loop.py

@@ -1131,10 +1131,12 @@ class AgentLoop:
         token-level sampling bumps don't help when the model picks
         the SAME serialized args every time.
 
-        Conservative thresholds — only fires on truly pathological
-        repeat counts that would never be a "valid retry":
+        Thresholds tuned for 45-prompt session windows (stress sessions
+        reset every 45 prompts — a threshold of 12 never fires in practice
+        because the model loops 4-8 times then moves on; admiral advisories
+        fire at 3 but the model ignores them):
           search_replace, write_file, bash: after 8 identical calls
-          read_file, grep, glob, ls: after 12 identical calls
+          read_file, grep, glob, ls: after 5 identical calls
         """
         args_str = json.dumps(tool_call.args_dict, sort_keys=True, default=str)
         sig = hashlib.sha256(
@@ -1143,9 +1145,13 @@ class AgentLoop:
         count, last_result = self._tool_call_history.get(sig, (0, ""))
         tool_name = tool_call.tool_name
         is_readonly = tool_name in ("grep", "read_file", "glob", "ls")
-        threshold = 12 if is_readonly else 8
+        threshold = 5 if is_readonly else 8
         if count < threshold:
             return None
+        # Increment so the count escalates on every repeated fire, giving the
+        # model a growing signal that nothing has changed.  Preserve last_result
+        # so the message always shows the real bash/tool output, not a prior NOTE.
+        self._tool_call_history[sig] = (count + 1, last_result)
         return (
             f"NOTE: this exact call to `{tool_name}` has been made "
             f"{count} times this session with identical arguments. "
@@ -1505,9 +1511,23 @@ class AgentLoop:
                 self.stats.tool_calls_failed += 1
             self._handle_tool_response(tool_call, error_msg, "failure", decision)
 
+    def _silence_suppressed_failures(self, suppressed: list) -> None:
+        """Add tool result messages for hallucinated tools without TUI events.
+
+        Keeps message history well-formed (assistant tool_call → tool result)
+        while hiding the error from the TUI to avoid confusing the user.
+        """
+        for failed in suppressed:
+            error_msg = f"<{TOOL_ERROR_TAG}>{failed.tool_name}: {failed.error}</{TOOL_ERROR_TAG}>"
+            self.messages.append(
+                self.format_handler.create_failed_tool_response_message(failed, error_msg)
+            )
+            self.stats.tool_calls_failed += 1
+
     async def _handle_tool_calls(
         self, resolved: ResolvedMessage
     ) -> AsyncGenerator[ToolCallEvent | ToolResultEvent | ToolStreamEvent | AssistantEvent]:
+        self._silence_suppressed_failures(resolved.suppressed_failures)
         async for event in self._emit_failed_tool_events(resolved.failed_calls):
             yield event
         for tool_call in resolved.tool_calls:
@@ -1703,10 +1723,10 @@ class AgentLoop:
         Runs every turn but is a no-op when nothing exceeds the caps.
         Truncation is in-place and idempotent.
         """
-        KEEP_RECENT = 6              # last N tool messages stay full
-        SOFT_CAP_BYTES = 800         # tool result longer than this gets shrunk
-        HEAD_BYTES = 400             # bytes kept from the head
-        TAIL_BYTES = 100             # bytes kept from the tail
+        KEEP_RECENT = 4              # last N tool messages stay full
+        SOFT_CAP_BYTES = 500         # tool result longer than this gets shrunk
+        HEAD_BYTES = 200             # bytes kept from the head
+        TAIL_BYTES = 60              # bytes kept from the tail
 
         if len(self.messages) < KEEP_RECENT + 4:
             return
@@ -2334,7 +2354,16 @@ class AgentLoop:
                 if replace_last_tool:
                     msg.content = f"[SYSTEM: {text}]"
                 else:
-                    msg.content = (msg.content or "") + f"\n\n[SYSTEM: {text}]"
+                    content = msg.content or ""
+                    # Cap at 2 accumulated system notes per message; replace the
+                    # last one when the limit is exceeded so repeated admiral
+                    # interventions don't unboundedly bloat the context.
+                    _SYS_PREFIX = "\n\n[SYSTEM: "
+                    if content.count(_SYS_PREFIX) >= 2:
+                        last_idx = content.rfind(_SYS_PREFIX)
+                        msg.content = content[:last_idx] + _SYS_PREFIX + text + "]"
+                    else:
+                        msg.content = content + _SYS_PREFIX + text + "]"
                 return
 
         # Second try: append to last user message
@@ -2370,6 +2399,30 @@ class AgentLoop:
         if len(recent_sr) >= 2 and recent_sr[0] == recent_sr[1]:
             return "WARNING|search_replace"
 
+        # Early check: write_file with _truncated args twice in a row for the
+        # same path.  format.py already embeds the file content in the error,
+        # but Gemma 4 ignores the advisory and retries identically.  Mute
+        # write_file for 1 turn so the model must use read_file or
+        # search_replace instead — same pattern as the search_replace check.
+        recent_wf_truncated: list[str] = []
+        for msg in reversed(self.messages[-20:]):
+            if msg.role == Role.assistant and msg.tool_calls:
+                for tc in msg.tool_calls:
+                    if tc.function and tc.function.name == "write_file":
+                        try:
+                            args = json.loads(tc.function.arguments or "{}")
+                            if args.get("_truncated"):
+                                p = (args.get("file_path") or args.get("path") or "")
+                                recent_wf_truncated.append(p)
+                        except (json.JSONDecodeError, AttributeError):
+                            pass
+                if len(recent_wf_truncated) >= 2:
+                    break
+        if (len(recent_wf_truncated) >= 2
+                and recent_wf_truncated[0] == recent_wf_truncated[1]):
+            self._hot_tool_path = ("write_file", recent_wf_truncated[0])
+            return "FORCE_STOP"
+
         sigs: list[str] = []
         tool_names: list[str] = []
         lookback = 0

{drydock_cli-2.7.6 → drydock_cli-2.7.22}/drydock/core/llm/format.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import logging
 import re as _re
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
@@ -165,9 +166,17 @@ class ResolvedMessage(BaseModel):
     model_config = ConfigDict(frozen=True)
     tool_calls: list[ResolvedToolCall]
     failed_calls: list[FailedToolCall] = Field(default_factory=list)
+    # Hallucinated tools: need a tool result in message history (to keep the
+    # conversation well-formed) but should NOT be shown as errors in the TUI.
+    suppressed_failures: list[FailedToolCall] = Field(default_factory=list)
 
 
 class APIToolFormatHandler:
+    def __init__(self) -> None:
+        # Track per-path truncated-history write_file retries so we can
+        # escalate on 2nd+ identical failures (model ignores advisory-only msgs).
+        self._truncated_hit_count: dict[str, int] = {}
+
     @property
     def name(self) -> str:
         return "api"
@@ -346,12 +355,25 @@ class APIToolFormatHandler:
             "list_mcp_resources", "list_resources", "search_resources",
         }
 
+        suppressed_failures = []
         for parsed_call in parsed.tool_calls:
             tool_class = active_tools.get(parsed_call.tool_name)
             if not tool_class:
-                # Silently drop known hallucinated tools instead of
-                # showing an error in the TUI
+                # Hallucinated tools: add a tool result to keep the message
+                # history well-formed (prevents empty_after_tool loops) but
+                # route to suppressed_failures so the TUI doesn't show an error.
                 if parsed_call.tool_name in _IGNORE_TOOLS:
+                    suppressed_failures.append(
+                        FailedToolCall(
+                            tool_name=parsed_call.tool_name,
+                            call_id=parsed_call.call_id,
+                            error=(
+                                f"'{parsed_call.tool_name}' is not available. "
+                                f"Use only tools from your tool list: "
+                                f"{', '.join(sorted(active_tools.keys())[:8])}."
+                            ),
+                        )
+                    )
                     continue
                 failed_calls.append(
                     FailedToolCall(
@@ -367,6 +389,102 @@ class APIToolFormatHandler:
                 continue
 
             args_model, _ = tool_class._get_tool_args_results()
+
+            # Detect when model copied truncated-history args (our truncation
+            # code replaces large tool-call args with {_truncated, _original_bytes,
+            # path}).  Return a clear advisory instead of a pydantic traceback so
+            # the model re-does the call with real arguments rather than retrying
+            # the truncated form.
+            if (isinstance(parsed_call.raw_args, dict)
+                    and parsed_call.raw_args.get("_truncated")):
+                path_hint = (parsed_call.raw_args.get("path")
+                             or parsed_call.raw_args.get("file_path")
+                             or "")
+                # Track retry count per path to escalate on 2nd+ offense.
+                hit_key = path_hint or "<unknown>"
+                hit_count = self._truncated_hit_count.get(hit_key, 0) + 1
+                self._truncated_hit_count[hit_key] = hit_count
+                escalate = hit_count >= 2
+
+                # Auto-embed the current file content so the model can
+                # rewrite immediately without an extra read_file round-trip.
+                file_embed = ""
+                if path_hint:
+                    try:
+                        p = Path(path_hint)
+                        if p.exists() and p.is_file():
+                            raw = p.read_text(errors="replace")
+                            lines = raw.splitlines()
+                            max_lines = 120
+                            if len(lines) <= max_lines:
+                                file_embed = (
+                                    f"\n\nCurrent file content of `{path_hint}`:\n"
+                                    f"```\n{raw}\n```\n"
+                                    f"Rewrite it now using write_file with the correct content."
+                                )
+                            else:
+                                snippet = "\n".join(lines[:max_lines])
+                                file_embed = (
+                                    f"\n\nCurrent file content of `{path_hint}` "
+                                    f"(first {max_lines} of {len(lines)} lines):\n"
+                                    f"```\n{snippet}\n```\n"
+                                    f"Use read_file to see the rest, then rewrite with write_file."
+                                )
+                    except Exception:
+                        pass
+                if not file_embed and path_hint:
+                    file_embed = f" Re-read `{path_hint}` with read_file first."
+
+                if escalate:
+                    # Model is stuck in a truncated-template retry loop.
+                    # Show project files and give a concrete directive.
+                    try:
+                        py_files = sorted(
+                            str(p2.relative_to(Path.cwd()))
+                            for p2 in Path.cwd().rglob("*.py")
+                            if "__pycache__" not in str(p2) and ".git" not in str(p2)
+                        )[:20]
+                        dir_listing = "\n".join(f"  {f}" for f in py_files)
+                    except Exception:
+                        dir_listing = "  (could not list files)"
+                    tool_name_hint = parsed_call.tool_name
+                    if tool_name_hint == "search_replace":
+                        recovery_hint = (
+                            f"Use read_file on '{path_hint}' to see its current content, "
+                            f"then call search_replace with fresh <<<<<<< SEARCH / ======= / "
+                            f">>>>>>> REPLACE markers copied from the actual file text."
+                        )
+                    else:
+                        recovery_hint = (
+                            f"Use read_file on the target file, then call write_file "
+                            f"with fully typed content, OR use search_replace to make "
+                            f"targeted edits without rewriting the whole file."
+                        )
+                    escalation_suffix = (
+                        f"\n\n[REPEATED FAILURE #{hit_count}: your {tool_name_hint} call "
+                        f"keeps using a stale truncated template for '{path_hint}'. "
+                        f"You MUST NOT copy args from history. "
+                        f"Current .py files in project:\n{dir_listing}\n"
+                        f"{recovery_hint}]"
+                    )
+                else:
+                    escalation_suffix = ""
+
+                failed_calls.append(
+                    FailedToolCall(
+                        tool_name=parsed_call.tool_name,
+                        call_id=parsed_call.call_id,
+                        error=(
+                            f"your call used a "
+                            f"truncated history entry as a template (it contained "
+                            f"'_truncated'/'_original_bytes' instead of real "
+                            f"arguments).{file_embed} Provide the full required "
+                            f"arguments.{escalation_suffix}"
+                        ),
+                    )
+                )
+                continue
+
             try:
                 validated_args = args_model.model_validate(parsed_call.raw_args)
                 resolved_calls.append(
@@ -378,15 +496,78 @@ class APIToolFormatHandler:
                     )
                 )
             except ValidationError as e:
+                error_str = str(e)
+                if (
+                    parsed_call.tool_name == "write_file"
+                    and "path" in error_str
+                    and "Field required" in error_str
+                ):
+                    # Try to infer path from the first comment line of content.
+                    # Gemma 4 frequently calls write_file(content="...") without path.
+                    content_val = parsed_call.raw_args.get("content", "")
+                    inferred_path: str | None = None
+                    if content_val:
+                        for _line in content_val.splitlines()[:5]:
+                            _line = _line.strip()
+                            _m = _re.match(
+                                r'^#\s+([\w./+-]+\.(?:py|js|ts|json|yaml|yml|toml|md|txt|sh|cfg|ini))\s*$',
+                                _line,
+                            )
+                            if _m:
+                                inferred_path = _m.group(1)
+                                break
+                    if inferred_path:
+                        try:
+                            _new_args = dict(parsed_call.raw_args)
+                            _new_args["path"] = inferred_path
+                            validated_args = args_model.model_validate(_new_args)
+                            resolved_calls.append(
+                                ResolvedToolCall(
+                                    tool_name=parsed_call.tool_name,
+                                    tool_class=tool_class,
+                                    validated_args=validated_args,
+                                    call_id=parsed_call.call_id,
+                                )
+                            )
+                            continue
+                        except ValidationError:
+                            pass
+                    # List project .py files as hints so the model can pick the right one
+                    _candidates: list[str] = []
+                    try:
+                        _candidates = [
+                            str(p.relative_to(Path.cwd()))
+                            for p in sorted(Path.cwd().rglob("*.py"))
+                            if "__pycache__" not in str(p) and ".git" not in str(p)
+                        ][:12]
+                    except Exception:
+                        pass
+                    _hint = (
+                        f"Project .py files: {', '.join(_candidates)}"
+                        if _candidates
+                        else "Use read_file or glob to list available files."
+                    )
+                    error_msg = (
+                        "missing required `path` parameter. "
+                        "You must pass BOTH `path` AND `content` as separate arguments: "
+                        'write_file(path="pkg/file.py", content="..."). '
+                        f"Do NOT omit `path`. {_hint}"
+                    )
+                else:
+                    error_msg = f"Invalid arguments: {e}"
                 failed_calls.append(
                     FailedToolCall(
                         tool_name=parsed_call.tool_name,
                         call_id=parsed_call.call_id,
-                        error=f"Invalid arguments: {e}",
+                        error=error_msg,
                     )
                 )
 
-        return ResolvedMessage(tool_calls=resolved_calls, failed_calls=failed_calls)
+        return ResolvedMessage(
+            tool_calls=resolved_calls,
+            failed_calls=failed_calls,
+            suppressed_failures=suppressed_failures,
+        )
 
     def create_tool_response_message(
         self, tool_call: ResolvedToolCall, result_text: str

{drydock_cli-2.7.6 → drydock_cli-2.7.22}/drydock/core/tools/builtins/bash.py

@@ -404,13 +404,38 @@ class Bash(
         self, *, command: str, stdout: str, stderr: str, returncode: int
     ) -> BashResult:
         if returncode != 0:
-            error_msg = f"Command failed: {command!r}\n"
-            error_msg += f"Return code: {returncode}"
-            if stderr:
-                error_msg += f"\nStderr: {stderr}"
-            if stdout:
-                error_msg += f"\nStdout: {stdout}"
-            raise ToolError(error_msg.strip())
+            # ADVISORY ONLY — never raise ToolError for non-zero exit codes.
+            # Raising blocks the model: it gets <tool_error> with no useful
+            # output, doesn't know if exit 1 means "no matches" (grep) or a
+            # real failure, and retries identically.  Same pattern as the
+            # timeout handler above.  Include a clear exit-code annotation so
+            # the model can reason about what happened.
+            # See feedback_no_tool_errors_for_loop_detection.md.
+            annotation = f"[Exit code {returncode}]"
+            if returncode < 0:
+                # Negative returncode means killed by a Unix signal.
+                try:
+                    sig_name = signal.Signals(-returncode).name
+                except ValueError:
+                    sig_name = f"signal {-returncode}"
+                annotation += (
+                    f" — process killed by {sig_name}."
+                    " If this command starts a server or long-running process,"
+                    " background it with `command &` and verify ports with `ss -tlnp`."
+                )
+            elif not stdout and not stderr:
+                annotation += " (no output)"
+                if returncode == 1:
+                    annotation += (
+                        " — for grep/find, exit code 1 means no matches found"
+                    )
+            annotated_stdout = (stdout + "\n" + annotation).strip() if stdout else annotation
+            return BashResult(
+                command=command,
+                stdout=annotated_stdout,
+                stderr=stderr,
+                returncode=returncode,
+            )
 
         return BashResult(
             command=command, stdout=stdout, stderr=stderr, returncode=returncode
@@ -445,7 +470,39 @@ class Bash(
                 )
             except TimeoutError:
                 await _kill_process_tree(proc)
-                raise self._build_timeout_error(args.command, timeout)
+                # ADVISORY ONLY — never raise ToolError on timeout; raising
+                # causes the model to retry the exact same command (loop).
+                # Track repeat timeouts per command and escalate the hint.
+                # See feedback_no_tool_errors_for_loop_detection.md.
+                timeout_state = self.state.__dict__.setdefault(
+                    "_bash_timeout_history", {}
+                )
+                count = timeout_state.get(args.command, 0) + 1
+                timeout_state[args.command] = count
+                if count == 1:
+                    hint = (
+                        "The command was killed. If it starts a server or "
+                        "long-running process, background it with `command &` "
+                        "instead of running it in the foreground."
+                    )
+                else:
+                    hint = (
+                        f"[TIMEOUT #{count}] You have timed out {count}x on "
+                        f"this exact command. Running it again will produce the "
+                        f"same result. STOP retrying. Background servers with "
+                        f"`&`, check existing listeners with `ss -tlnp`, or fix "
+                        f"the underlying cause before re-running."
+                    )
+                yield BashResult(
+                    command=args.command,
+                    stdout=(
+                        f"Command timed out after {timeout}s: {args.command!r}\n"
+                        f"{hint}"
+                    ),
+                    stderr="",
+                    returncode=124,
+                )
+                return
 
             encoding = _get_subprocess_encoding()
             stdout = (