drydock-cli 2.7.8__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.8 → drydock_cli-2.7.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: drydock-cli
-Version: 2.7.8
+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.8 → 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.8 → 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.8 → 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.8 → 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.8 → 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 = (

{drydock_cli-2.7.8 → drydock_cli-2.7.22}/drydock/core/tools/builtins/read_file.py

@@ -45,7 +45,7 @@ class ReadFileResult(BaseModel):
     content: str
     lines_read: int
     was_truncated: bool = Field(
-        description="True if the reading was stopped due to the max_read_bytes limit."
+        description="True if the reading was stopped due to the line limit or max_read_bytes limit."
     )
 
 
@@ -111,25 +111,48 @@ class ReadFile(
             and prior.get("offset") == args.offset
             and prior.get("limit") == args.limit
         ):
+            # Re-embed the cached content so the model has it even if the
+            # earlier tool_result was truncated by _truncate_old_tool_results.
+            # Pointing at a stale/truncated prior result causes re-read loops.
+            cached_content = prior.get("content", "")
+            prior_lines = prior.get("lines_read", 0)
+            dedup_count = prior.get("dedup_count", 0)
+            if dedup_count == 0:
+                header = "[Unchanged since last read — content re-embedded]\n"
+            else:
+                header = (
+                    f"[REPEATED READ #{dedup_count + 1}: file has not changed across your last "
+                    f"{dedup_count + 1} reads with these exact arguments. "
+                    f"Reading again will produce this same result. "
+                    f"To make progress: write or edit a file, use offset= to read a different section, "
+                    f"or move on to the next task.]\n"
+                )
+            if read_state is not None:
+                read_state[path_key] = {**prior, "dedup_count": dedup_count + 1}
             yield ReadFileResult(
                 path=path_key,
-                content=(
-                    "<system-reminder>\n"
-                    f"File unchanged since your earlier read this session "
-                    f"({file_path.name}, mtime unchanged, same offset/limit). "
-                    "Use the content from the earlier Read tool_result — "
-                    "do NOT re-read. If you need to take action, call "
-                    "search_replace or write_file on what you already have.\n"
-                    "</system-reminder>"
-                ),
-                lines_read=0,
-                was_truncated=True,
+                content=f"{header}{cached_content}",
+                lines_read=prior_lines,
+                was_truncated=prior.get("was_truncated", False),
             )
             return
 
         read_result = await self._read_file(args, file_path)
         content = "".join(read_result.lines)
 
+        # When stopped by the line limit (not byte limit), append a hint so
+        # the model knows to paginate with offset= instead of re-reading.
+        if (
+            read_result.was_truncated
+            and args.limit is not None
+            and len(read_result.lines) == args.limit
+        ):
+            next_offset = args.offset + args.limit
+            content += (
+                f"\n[lines {args.offset + 1}–{next_offset} shown; "
+                f"use offset={next_offset} to read more]"
+            )
+
         # Record read state so Write/Edit can enforce Read-before-Write
         # and so future re-reads can dedup against this one.
         if read_state is not None:
@@ -138,6 +161,8 @@ class ReadFile(
                 "timestamp": current_mtime,
                 "offset": args.offset,
                 "limit": args.limit,
+                "lines_read": len(read_result.lines),
+                "was_truncated": read_result.was_truncated,
             }
 
         yield ReadFileResult(
@@ -195,6 +220,7 @@ class ReadFile(
                         continue
 
                     if args.limit is not None and len(lines_to_return) >= args.limit:
+                        was_truncated = True
                         break
 
                     line_bytes = len(line.encode("utf-8"))
@@ -237,12 +263,45 @@ class ReadFile(
                 f"Security error: Cannot read path '{file_path}' outside of the project directory '{Path.cwd()}'."
             )
         except FileNotFoundError:
-            raise ToolError(f"File not found at: {file_path}")
+            raise ToolError(self._not_found_msg(file_path))
 
         if not resolved_path.exists():
-            raise ToolError(f"File not found at: {file_path}")
+            raise ToolError(self._not_found_msg(file_path))
         if resolved_path.is_dir():
-            raise ToolError(f"Path is a directory, not a file: {file_path}")
+            raise ToolError(self._is_dir_msg(file_path, resolved_path))
+
+    @staticmethod
+    def _not_found_msg(file_path: Path) -> str:
+        """Return 'File not found' error with parent directory listing for context."""
+        parent = file_path.parent if file_path.parent != file_path else Path(".")
+        try:
+            entries = sorted(p.name for p in parent.iterdir())
+            if entries:
+                listing = "\n".join(f"  {e}" for e in entries[:30])
+                suffix = f"\n  ... ({len(entries) - 30} more)" if len(entries) > 30 else ""
+                return (
+                    f"File not found at: {file_path}\n"
+                    f"Contents of {parent}/:\n{listing}{suffix}"
+                )
+        except (PermissionError, OSError):
+            pass
+        return f"File not found at: {file_path}"
+
+    @staticmethod
+    def _is_dir_msg(file_path: Path, resolved_path: Path) -> str:
+        """Return 'is a directory' error with directory listing so model can pick a file."""
+        try:
+            entries = sorted(p.name for p in resolved_path.iterdir())
+            if entries:
+                listing = "\n".join(f"  {e}" for e in entries[:30])
+                suffix = f"\n  ... ({len(entries) - 30} more)" if len(entries) > 30 else ""
+                return (
+                    f"Path is a directory, not a file: {file_path}\n"
+                    f"Contents of {file_path}/:\n{listing}{suffix}"
+                )
+        except (PermissionError, OSError):
+            pass
+        return f"Path is a directory, not a file: {file_path}"
 
     @classmethod
     def format_call_display(cls, args: ReadFileArgs) -> ToolCallDisplay: