feat(toolsets): one text object per tool, and ModelRetry for a fixable mistake

[DEENUU1]

Two commits, both about what a tool says to the model.

1. One text object per tool, with a Returns: — feat(toolsets): give each console tool one text object

Each tool's text is now one ToolText — summary, usage, coding, args, returns — instead of a description constant in one file and an argument docstring beside the function in another. The description is rendered from it; args becomes the per-argument text in the JSON schema.

The prose was rewritten against the house standard: what it does, when to use it and when to use another tool, every argument, and what comes back. That last part existed nowhere. Nothing said that grep answers in three shapes depending on output_mode, that glob lists 100 paths and grep 50 before summarising the rest as ... and N more, that read_file's offset counts from 0 while the printed line numbers count from 1, or that a failed execute still returns its output under Command failed (exit code N).

Also: profile="agent" drops the repository-specific guidance execute carried on every request (about 240 tokens across the seven tools a typical host registers), and descriptions now takes a ToolText as well as a string, with an unknown key raising UserError instead of being ignored.

2. ModelRetry for a mistake the model can fix — feat(toolsets): raise ModelRetry

Every failure used to be a returned string, including the ones the model had plainly got wrong: an old_string matching three places, a file edited between the read and the edit, a path that does not exist. It was told in a sentence indistinguishable from a real answer and left to notice.

Raises ModelRetry — a missing file, an offset past the end, an absent or ambiguous old_string, a stale read, a hashline hash that no longer matches.

Stays a returned string, deliberately — a non-zero exit from execute is a result to reason about rather than a malformed call; grep finding nothing is an answer; a dropped connection is not something different arguments would fix; and a permission refusal must never be a retry, since a retry prompt invites the model to look for a way around the rule. PERMISSION_DENIED_PREFIX is one constant PermissionGuard writes and toolsets/_failures.py reads, with a test holding both ends.

max_retries becomes a floor as well as a ceiling. ModelRetry past the budget ends the whole run with UnexpectedModelBehavior — so without the floor, a model that mistyped an old_string twice would kill a run that used to carry on: a regression hiding inside an improvement. On a tool's last attempt the message is returned rather than raised, so the worst case is exactly the old behaviour, and max_retries=0 reproduces it entirely.

tests/test_console_retry_budget.py proves that in a real run rather than by assertion: a FunctionModel sends the same ambiguous edit twice, and the message history is exactly one retry prompt followed by one tool return.

Verified

1713 tests, coverage 100%, pyright and mypy strict clean, mkdocs --strict builds, and the suite passes against the declared pydantic-ai floor 1.74.0 as well as 1.80.0 — RunContext.last_attempt and the __doc__ assignment are the two things that had to hold on both.

Not verified: no eval against a real model. Whether the new text changes behaviour gets measured in agenticos.

Next, not in this PR

agenticos takes profile="agent", uses ToolText.summary for the Builder's catalogue, bumps its pin, and gets the same failure taxonomy written down and applied to its own capabilities — most already raise ModelRetry; channel_tools returns strings for a documented and correct reason; code_execution.run_python returning Execution failed: ... for a SyntaxError in code the model itself wrote is the one clear mismatch.