voidx 3.2.2__tar.gz → 3.3.0__tar.gz

{voidx-3.2.2 → voidx-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voidx
-Version: 3.2.2
+Version: 3.3.0
 Summary: A coding agent that quantifies everything and solves with tools, not fuzzy prompts.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{voidx-3.2.2 → voidx-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "voidx"
-version = "3.2.2"
+version = "3.3.0"
 description = "A coding agent that quantifies everything and solves with tools, not fuzzy prompts."
 readme = "README.md"
 requires-python = ">=3.11"

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/__init__.py

@@ -1,3 +1,3 @@
 """VoidX - A coding agent that quantifies everything."""
 
-__version__ = "3.2.2"
+__version__ = "3.3.0"

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/agent/graph/compaction_coordinator.py

@@ -189,7 +189,7 @@ class GraphCompactionCoordinator:
         if host._ui.via_events():
             await host._ui.events.emit(StatusUpdated(
                 status_id="compaction",
-                label="Compacting context",
+                label="Compacting",
                 detail=_compaction_status_detail(total_tokens, force=force, preflight=preflight),
                 stage="compacting",
                 display="record_only",
@@ -198,7 +198,7 @@ class GraphCompactionCoordinator:
             host._ui.ui.print(
                 "[yellow]Context overflow — compacting...[/yellow]"
                 if not force
-                else "[yellow]Compacting context...[/yellow]"
+                else "[yellow]Compacting...[/yellow]"
             )
 
         runtime_prefix = _runtime_prefix(messages)
@@ -251,9 +251,10 @@ class GraphCompactionCoordinator:
                     retry_label = f" (attempt {attempt})" if attempt > 1 else ""
                     await host._ui.events.emit(StatusUpdated(
                         status_id="compaction",
-                        label="Compacting context",
+                        label="Compacting",
                         detail=f"summarizing {len(head_msgs)} old messages{retry_label}",
                         stage="compacting",
+                        display="record_only",
                     ))
                 summary = await run_agent(head_msgs, previous_summary)
                 if summary:
@@ -270,6 +271,7 @@ class GraphCompactionCoordinator:
                             label="Compaction agent failed",
                             detail=f"{e}; retrying ({attempt}/{COMPACTION_MAX_RETRIES})",
                             stage="compacting",
+                            display="record_only",
                         ))
                     else:
                         host._ui.ui.print(f"[dim]Compaction agent failed ({e}) — retrying ({attempt}/{COMPACTION_MAX_RETRIES})[/dim]")
@@ -288,6 +290,7 @@ class GraphCompactionCoordinator:
                     label="Compaction agent failed",
                     detail=f"{failure_detail}; using extracted summary",
                     stage="compacting",
+                    display="record_only",
                 ))
             else:
                 err_msg = f" ({failure_detail})"

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/agent/graph/core/_voidx_graph.py

@@ -399,6 +399,7 @@ class VoidXGraph(
 
         ok = False
         run_metadata: dict[str, object] = {}
+        result = ""
         try:
             kwargs = {
                 "sub_messages": sub_buffer,
@@ -439,6 +440,7 @@ class VoidXGraph(
                     ok=ok,
                     elapsed=time.monotonic() - started_at,
                     finish_reason=str(run_metadata.get("finish_reason") or ("final_answer" if ok else "error")),
+                    summary=result if ok else "",
                 ))
             if self._session:
                 await append_subagent_event(session_id, agent_run_id, {

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/agent/graph/subagent.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import re
 import time
 
 from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
@@ -43,6 +44,7 @@ from voidx.runtime.ui_port import AgentUiPort, runtime_ui_port
 
 
 _SAFETY_STEP_LIMIT = 50
+_RESULT_CONTRACT_RETRY_LIMIT = 2
 
 async def run_subagent(
     agent_def: AgentDef,
@@ -105,6 +107,8 @@ async def run_subagent(
     )
     guard_state = RuntimeGuardState(wall_clock=WallClockGuardState.for_subagent())
     pending_guard_guidance: list[str] = []
+    contract_retry_count = 0
+    has_successful_tool_work = False
 
     context, context_cache = RuntimeContextBuilder(
         config=context_config,
@@ -212,6 +216,18 @@ async def run_subagent(
 
             if not assistant_msg.tool_calls:
                 text = extract_text(assistant_msg)
+                if has_successful_tool_work and not _satisfies_result_contract(text, result_contract):
+                    if contract_retry_count < _RESULT_CONTRACT_RETRY_LIMIT:
+                        contract_retry_count += 1
+                        step -= 1
+                        guidance = _result_contract_retry_message(result_contract)
+                        messages.append(HumanMessage(content=guidance))
+                        continue
+                    if tracker:
+                        tracker.update(task_id, last_output=text[:200])
+                        tracker.finish(task_id, "completed")
+                    mark_finished("contract_unsatisfied")
+                    return text
                 if tracker:
                     tracker.update(task_id, last_output=text[:200])
                     tracker.finish(task_id, "completed")
@@ -318,6 +334,7 @@ async def run_subagent(
                 if metadata.get("runtime_guard"):
                     continue
                 if result_ok(item["result"]):
+                    has_successful_tool_work = True
                     guard_state.tool_failures.record_success(item["tool_call"])
                     continue
                 key = build_failure_key(item["tool_call"], item["result"])
@@ -391,3 +408,46 @@ def _task_payload(task_description: str, result_contract) -> str:
             "Return the final answer using this contract."
         )
     return "\n\n".join(parts)
+
+
+def _result_contract_fields(result_contract) -> list[str]:
+    result_format = str(getattr(result_contract, "format", "") or "")
+    fields: list[str] = []
+    for raw_part in result_format.split(","):
+        part = raw_part.strip()
+        if not part:
+            continue
+        match = re.match(r"([A-Za-z_][A-Za-z0-9_]*)", part)
+        if match:
+            fields.append(match.group(1))
+    return fields
+
+
+def _satisfies_result_contract(text: str, result_contract) -> bool:
+    fields = _result_contract_fields(result_contract)
+    if not fields:
+        return True
+    if not text.strip():
+        return False
+
+    matched = [
+        field
+        for field in fields
+        if re.search(rf"(?im)^\s*(?:[-*]\s*)?{re.escape(field)}\s*[:=]", text)
+    ]
+    required = 1 if len(fields) == 1 else 2
+    if fields[0] not in matched:
+        return False
+    return len(matched) >= required
+
+
+def _result_contract_retry_message(result_contract) -> str:
+    schema_name = str(getattr(result_contract, "schema_name", "") or "agent_result")
+    result_format = str(getattr(result_contract, "format", "") or "").strip()
+    return (
+        "Your previous response did not satisfy the child-agent result contract. "
+        "Do not return raw tool output or code snippets as the final answer.\n"
+        "Summarize the completed delegated task using the required contract:\n"
+        f"- schema_name: {schema_name}\n"
+        f"- format: {result_format}"
+    )

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/agent/prompts.py

@@ -116,6 +116,13 @@ BASE_SYSTEM = BaseSystemPrompt(
         PromptRule(detail="Assess before acting — evaluate what's already known and what's still needed."),
         PromptRule(detail="Stay aligned with the user's actual goal."),
         PromptRule(detail="Pick the smallest next action that makes progress toward the goal."),
+        PromptRule(
+            detail=(
+                "Delegate to child agents only for parallel independent tasks or when the user "
+                "explicitly asks. Do not delegate single-file reads, simple searches, or "
+                "straightforward tasks you can do directly."
+            ),
+        ),
         PromptRule(detail="skill can return project/global skill bodies for the current turn."),
         PromptRule(
             detail=(

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/permission/rules.py

@@ -38,6 +38,7 @@ BASIC_RULES: Ruleset = [
     Rule(permission="compact", pattern="*", action="allow"),
     Rule(permission="task_status", pattern="*", action="allow"),
     Rule(permission="skill", pattern="*", action="allow"),
+    Rule(permission="skill", pattern="create", action="ask"),
     Rule(permission="lsp", pattern="*", action="allow"),
     Rule(permission="agent", pattern="voidx", action="allow"),
     Rule(permission="edit", pattern="*", action="ask"),
@@ -118,6 +119,8 @@ def build_pattern(tool: str, args: dict) -> str:
         return "voidx"
     if tool == "git":
         return "read" if _is_read_only_git_tool_command(args) else "write"
+    if tool == "skill":
+        return "create" if args.get("op") == "create" else "*"
     return "*"
 
 
@@ -359,10 +362,14 @@ def _is_read_only_git_ref_command(subcommand: str, args: list[str]) -> bool:
 def capability_for_tool(tool: str, args: dict) -> PermissionCapability:
     if tool in {
         "read", "glob", "grep", "webfetch", "websearch", "todo", "task_status",
-        "skill", "workflow", "compact",
+        "workflow", "compact",
         "lsp",
     }:
         return PermissionCapability.READ_TOOLS
+    if tool == "skill":
+        if args.get("op") == "create":
+            return PermissionCapability.FILE_WRITE
+        return PermissionCapability.READ_TOOLS
     if tool in {"file", "write", "replace"}:
         return PermissionCapability.FILE_WRITE
     if tool == "bash":

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/skills/registry.py

@@ -2,14 +2,16 @@
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from voidx.skills.schema import SkillDefinition, SkillMeta, SkillScope
 
 SKILL_FILENAME = "SKILL.md"
 DEFAULT_BUNDLED_DIR = Path(__file__).resolve().parent / "bundled"
+SKILL_NAME_RE = re.compile(r"^(?=.{1,64}$)[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
 
 
 @dataclass
@@ -72,6 +74,44 @@ class SkillRegistry:
         self._cache = None
         self._cache_signature = None
 
+    def create_skill(
+        self,
+        name: str,
+        description: str,
+        body: str,
+        *,
+        scope: Literal["project", "global"] = "project",
+    ) -> Path | None:
+        """Create a SKILL.md file. Returns the path, or None if it already exists.
+
+        Security: name is validated against SKILL_NAME_RE on the first line.
+        This is the sole path-escape defense since sandbox skips the check
+        (skill create has no file_path arg). Must not rely on tool-layer validation.
+        """
+        if not SKILL_NAME_RE.match(name):
+            raise ValueError(
+                f"Invalid skill name '{name}': must be 1-64 chars, lowercase "
+                f"alphanumeric with hyphens, not starting/ending with a hyphen."
+            )
+
+        root = self.project_dir if scope == "project" else self.global_dir
+        path = root / name / SKILL_FILENAME
+        if path.exists():
+            return None
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        frontmatter = (
+            "---\n"
+            f"name: {name}\n"
+            f"description: {description}\n"
+            "enabled: true\n"
+            "---\n\n"
+        )
+        path.write_text(frontmatter + body, encoding="utf-8")
+        self.invalidate()
+        return path
+
+
     def get(self, name: str) -> SkillDefinition | None:
         target = normalize_skill_name(name)
         for skill in self.discover():

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/agent.py

@@ -127,15 +127,8 @@ _RESULT_PRESETS: dict[str, AgentResultContract] = {
 class AgentTool(BaseTool):
     id = "agent"
     description = (
-        "Start an isolated child agent for a delegated task. Use ONLY when "
-        "you need to run multiple independent tasks in parallel, or the user "
-        "explicitly asks for a child agent. Do not use for single-file reads, "
-        "simple searches, or straightforward tasks you can do directly. Each "
-        "call must include mode, task, and one concrete target. Use "
-        "success_criteria for implement and feedback modes, and result_preset "
-        "when the child output shape should be explicit. "
-        "The child agent receives your task description and runtime context, "
-        "but not caller conversation history."
+        "Start an isolated child agent for a delegated task. The child receives "
+        "the task brief and runtime context, but not caller conversation history."
     )
 
     def __init__(
@@ -196,19 +189,21 @@ class AgentTool(BaseTool):
 
         if self._agent_resolver is None:
             return ToolResult(
-                output=f"Child agent execution not available. Task: {normalized.description[:200]}"
+                output=f"Child agent execution not available. Task: {normalized.description[:200]}",
+                metadata={"error": True, "reason": "no_resolver"},
             )
 
         agent_def = self._agent_resolver(requested_agent) if self._agent_resolver else None
         if not agent_def:
             available = self._available_agents
-            return ToolResult(output=f"Unknown child agent: {inp.agent}. Available: {available}")
+            return ToolResult(output=f"Unknown child agent: {inp.agent}. Available: {available}", metadata={"error": True, "reason": "unknown_agent"})
 
         agent_def_name = str(getattr(agent_def, "name", inp.agent))
 
         if not self._run_child_agent:
             return ToolResult(
-                output=f"Child agent execution not available. Task: {normalized.description[:200]}"
+                output=f"Child agent execution not available. Task: {normalized.description[:200]}",
+                metadata={"error": True, "reason": "no_runner"},
             )
 
         try:
@@ -235,7 +230,7 @@ class AgentTool(BaseTool):
         except Exception as exc:
             return ToolResult(
                 output=f"Child agent '{agent_def_name}' failed: {exc}",
-                metadata={"agent": agent_def_name, "error": str(exc)},
+                metadata={"agent": agent_def_name, "error": True, "reason": "exception", "detail": str(exc)[:200]},
             )
 
 

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/bash/core.py

@@ -81,11 +81,6 @@ def _strip_cd_prefix(command: str) -> str:
     return remainder
 
 
-_UNHINTABLE_GIT_SUBCOMMANDS = frozenset({
-    "push", "pull", "merge", "rebase", "cherry-pick",
-    "reset", "checkout", "fetch", "clone", "init",
-    "submodule", "filter-branch", "bisect",
-})
 
 _GIT_GLOBAL_OPTIONS_WITH_VALUE = frozenset({
     "-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path",

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/bash/hint/file.py

@@ -132,7 +132,7 @@ def _hint_write_echo(stripped: str, words: list[str]) -> RouteHint | None:
         )
     return RouteHint(
         tool_id="file", ui_label="→ file",
-        llm_hint=f'Prefer file(file_path="{path}", op="create") then line(file_path="{path}", op="append", new_string="{content}") for file tracking and diff output.',
+        llm_hint=f'Prefer file(file_path="{path}", op="create") then write(file_path="{path}", op="append", new_string="{content}") for file tracking and diff output.',
     )
 
 
@@ -180,7 +180,7 @@ def _hint_write_heredoc(stripped: str) -> RouteHint | None:
         )
     return RouteHint(
         tool_id="file", ui_label="→ file",
-        llm_hint=f'Prefer file(file_path="{path}", op="create") then line(file_path="{path}", op="append", new_string="{content}") for file tracking and diff output.',
+        llm_hint=f'Prefer file(file_path="{path}", op="create") then write(file_path="{path}", op="append", new_string="{content}") for file tracking and diff output.',
     )
 
 

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/bash/hint/git.py

@@ -5,20 +5,16 @@ from __future__ import annotations
 from voidx.tools.bash.core import (
     RouteHint,
     _git_subcommand,
-    _UNHINTABLE_GIT_SUBCOMMANDS,
 )
 
 
 def _hint_git(stripped: str, words: list[str]) -> RouteHint | None:
-    subcommand, rest = _git_subcommand(words)
+    subcommand, _ = _git_subcommand(words)
     if not subcommand:
         return None
-    if subcommand in _UNHINTABLE_GIT_SUBCOMMANDS:
-        return None
     git_args = stripped[len("git"):].strip()
-    if '"' in git_args:
-        return None
+    llm_hint = f"Prefer git tool with args={git_args!r} for structured output."
     return RouteHint(
         tool_id="git", ui_label="→ git",
-        llm_hint=f'Prefer git tool with args="{git_args}" for structured output.',
-    )
+        llm_hint=llm_hint,
+    )

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/bash/hint/search.py

@@ -233,16 +233,16 @@ def _hint_sed(words: list[str]) -> RouteHint | None:
                 line_no = int(line_prefix)
                 return RouteHint(
                     tool_id="replace", ui_label="→ replace",
-                    llm_hint=f'Prefer replace(file_path="{path}", start_no={line_no}, end_no={line_no}, prefix="{old_text}", suffix="{old_text}", new_string="{new_text}") — prefix/suffix are line content anchors for locating the edit, new_string is the replacement. Enables staleness checking and diff output.',
+                    llm_hint=f'Prefer replace(file_path="{path}", start_no={line_no}, end_no={line_no}, start_anchor="{old_text}", end_anchor="{old_text}", new_string="{new_text}").',
                 )
             if is_global:
                 return RouteHint(
                     tool_id="replace", ui_label="→ replace",
-                    llm_hint=f'For global substitution: first read {path} to locate lines, then use replace(file_path, start_no, end_no, prefix="{old_text}", suffix="{old_text}", new_string="{new_text}") — prefix/suffix are line content anchors for locating the edit.',
+                    llm_hint=f'For global substitution: first read {path} to locate lines, then use replace(file_path, start_no, end_no, start_anchor="{old_text}", end_anchor="{old_text}", new_string="{new_text}").',
                 )
             return RouteHint(
                 tool_id="replace", ui_label="→ replace",
-                llm_hint=f'Prefer replace(file_path="{path}", start_no, end_no, prefix="{old_text}", suffix="{old_text}", new_string="{new_text}") — prefix/suffix are line content anchors for locating the edit, new_string is the replacement. Enables staleness checking and diff output.',
+                llm_hint=f'Prefer replace(file_path="{path}", start_no, end_no, start_anchor="{old_text}", end_anchor="{old_text}", new_string="{new_text}").',
             )
 
     m = _SED_RANGE_DELETE.match(script)
@@ -250,7 +250,7 @@ def _hint_sed(words: list[str]) -> RouteHint | None:
         start, end = int(m.group(1)), int(m.group(2))
         return RouteHint(
             tool_id="replace", ui_label="→ replace",
-            llm_hint=f'For line range deletion: first read {path} to see lines {start}-{end}, then use replace(file_path="{path}", start_no={start}, end_no={end}, prefix="...", suffix="...", new_string="").',
+            llm_hint=f'For line range deletion: first read {path} to see lines {start}-{end}, then use replace(file_path="{path}", start_no={start}, end_no={end}, start_anchor="...", end_anchor="...", new_string="").',
         )
 
     m = _SED_LINE_DELETE.match(script)
@@ -258,14 +258,14 @@ def _hint_sed(words: list[str]) -> RouteHint | None:
         line_no = int(m.group(1))
         return RouteHint(
             tool_id="replace", ui_label="→ replace",
-            llm_hint=f'For single line deletion: first read {path} to see line {line_no}, then use replace(file_path="{path}", start_no={line_no}, end_no={line_no}, prefix="...", suffix="...", new_string="").',
+            llm_hint=f'For single line deletion: first read {path} to see line {line_no}, then use replace(file_path="{path}", start_no={line_no}, end_no={line_no}, start_anchor="...", end_anchor="...", new_string="").',
         )
     m = _SED_PATTERN_DELETE.match(script)
     if m:
         pat = m.group(1)
         return RouteHint(
             tool_id="replace", ui_label="→ replace",
-            llm_hint=f'For pattern-based deletion: first grep "{pat}" {path} to locate lines, then use replace(..., new_string="").',
+            llm_hint=f'For pattern-based deletion: first grep "{pat}" {path} to locate matching lines, then use replace(file_path="{path}", start_no, end_no, start_anchor, end_anchor, new_string="") with the matched line numbers and content.',
         )
 
     return None

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/bash/tool.py

@@ -27,7 +27,10 @@ class BashTool(BaseTool):
         return model_to_json_schema(BashInput)
 
     async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
-        inp = BashInput.model_validate(args)
+        try:
+            inp = BashInput.model_validate(args)
+        except Exception as exc:
+            return ToolResult(output=f"Invalid arguments: {exc}", metadata={"error": True})
 
         blocked = _check_command(inp.command)
         if blocked:
@@ -35,7 +38,7 @@ class BashTool(BaseTool):
             return ToolResult(
                 output=json.dumps(payload, ensure_ascii=False),
                 display=blocked,
-                metadata={"command": inp.command, "blocked": True},
+                metadata={"command": inp.command, "blocked": True, "error": True},
             )
 
         blocked = _sandbox_denial(inp.command, ctx)
@@ -44,7 +47,7 @@ class BashTool(BaseTool):
             return ToolResult(
                 output=json.dumps(payload, ensure_ascii=False),
                 display=blocked,
-                metadata={"command": inp.command, "blocked": True},
+                metadata={"command": inp.command, "blocked": True, "error": True},
             )
 
         hint = try_hint(inp.command)
@@ -83,7 +86,7 @@ class BashTool(BaseTool):
             return ToolResult(
                 output=json.dumps(payload, ensure_ascii=False),
                 display=display,
-                metadata={"command": inp.command, "exit_code": -1, "timeout": True},
+                metadata={"command": inp.command, "exit_code": -1, "timeout": True, "error": True},
             )
 
         stdout_text = stdout.decode("utf-8", errors="replace") if stdout else ""
@@ -117,6 +120,7 @@ class BashTool(BaseTool):
                 "command": inp.command,
                 "exit_code": exit_code,
                 "ok": exit_code == 0,
+                **({"error": True} if exit_code != 0 else {}),
             },
         )
 

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/clarify.py

@@ -45,7 +45,10 @@ class ClarifyTool(BaseTool):
         return model_to_json_schema(ClarifyInput)
 
     async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
-        inp = ClarifyInput.model_validate(args)
+        try:
+            inp = ClarifyInput.model_validate(args)
+        except Exception as exc:
+            return ToolResult(output=f"Invalid arguments: {exc}", metadata={"error": True})
         if ctx.interact is None:
             return ToolResult(
                 title="clarify: unavailable",

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/compact_context.py

@@ -37,7 +37,10 @@ class CompactContextTool(BaseTool):
         return model_to_json_schema(CompactContextInput)
 
     async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
-        inp = CompactContextInput.model_validate(args)
+        try:
+            inp = CompactContextInput.model_validate(args)
+        except Exception as exc:
+            return ToolResult(output=f"Invalid arguments: {exc}", metadata={"error": True})
         summary = inp.summary.strip()
         tail_anchor_id = inp.tail_anchor_id.strip()
         return ToolResult(

{voidx-3.2.2 → voidx-3.3.0}/src/voidx/tools/file_ops/edit_execute.py

@@ -25,7 +25,7 @@ from .types import DisplayLines, ResolvedEdit
 
 
 class FileReplaceInput(BaseModel):
-    file_path: str = Field(description="Path to edit")
+    file_path: str = Field(description="Absolute or relative path to the file")
     start_no: int = Field(
         ge=1,
         description=(
@@ -40,26 +40,22 @@ class FileReplaceInput(BaseModel):
             "Use the line number from the latest read output."
         ),
     )
-    prefix: str = Field(
+    start_anchor: str = Field(
         description=(
-            "Substring expected anywhere on the first line to replace. "
-            "Use an empty string only when the first line is empty. "
-            "Aim for a distinctive snippet."
+            "Content anchor on the first line to replace — a substring "
+            "expected anywhere on that line. Use an empty string only "
+            "when the first line is empty. Aim for a distinctive snippet."
         ),
     )
-    suffix: str = Field(
+    end_anchor: str = Field(
         description=(
-            "Substring expected anywhere on the last line to replace. "
-            "Use an empty string only when the last line is empty. "
-            "Aim for a distinctive snippet."
+            "Content anchor on the last line to replace — a substring "
+            "expected anywhere on that line. Use an empty string only "
+            "when the last line is empty. Aim for a distinctive snippet."
         ),
     )
     new_string: str = Field(
-        description=(
-            "Replacement content. May contain any number of lines. "
-            "A trailing newline does not add an extra blank line; "
-            "start with a newline only when an intentional blank first line is desired."
-        ),
+        description="Replacement content. May contain any number of lines.",
     )
 
     @model_validator(mode="after")
@@ -74,7 +70,7 @@ class FileReplaceTool(BaseTool):
     description = (
         "Replace whole lines in a file. "
         "Provide the exact start_no/end_no from the latest read output, "
-        "plus prefix/suffix substrings from the first and last lines. "
+        "plus start_anchor/end_anchor substrings from the first and last lines. "
         "Read the target lines first."
     )
 
@@ -82,14 +78,17 @@ class FileReplaceTool(BaseTool):
         return model_to_json_schema(FileReplaceInput)
 
     async def execute(self, args: dict, ctx: ToolContext) -> ToolResult:
-        inp = FileReplaceInput.model_validate(args)
+        try:
+            inp = FileReplaceInput.model_validate(args)
+        except Exception as exc:
+            return ToolResult(output=f"Invalid arguments: {exc}", metadata={"error": True})
         return await _execute_text_replace(
             ctx,
             file_path=inp.file_path,
             start_no=inp.start_no,
             end_no=inp.end_no,
-            prefix=inp.prefix,
-            suffix=inp.suffix,
+            start_anchor=inp.start_anchor,
+            end_anchor=inp.end_anchor,
             new_string=inp.new_string,
             tool_name=self.id,
         )
@@ -114,8 +113,8 @@ async def _execute_text_replace(
     file_path: str,
     start_no: int,
     end_no: int,
-    prefix: str,
-    suffix: str,
+    start_anchor: str,
+    end_anchor: str,
     new_string: str,
     tool_name: str,
 ) -> ToolResult:
@@ -126,12 +125,12 @@ async def _execute_text_replace(
 
     original = path.read_text(encoding="utf-8", errors="replace")
     display = _split_display_lines(original)
-    match = _find_text_segment(display.lines, start_no, end_no, prefix, suffix)
+    match = _find_text_segment(display.lines, start_no, end_no, start_anchor, end_anchor)
     if isinstance(match, str):
         return ToolResult(output=match, metadata={"error": True})
 
     _, _, start_line, end_line = match
-    coverage_error = check_read_coverage(ctx, path, start_line, end_line)
+    coverage_error = check_read_coverage(ctx, path, start_line, end_line, display_path=file_path)
     if coverage_error:
         return ToolResult(output=f"Edit 0: {coverage_error}", metadata={"error": True})
 
@@ -222,7 +221,7 @@ async def _apply_resolved_edits(
             continue
         if edit.operation == "insert" and edit.start_line == total_lines and edit.end_line == total_lines:
             continue
-        coverage_error = check_read_coverage(ctx, path, edit.start_line, edit.end_line)
+        coverage_error = check_read_coverage(ctx, path, edit.start_line, edit.end_line, display_path=file_path)
         if coverage_error:
             return ToolResult(output=f"Edit {i}: {coverage_error}", metadata={"error": True})