v0.2.28

Two changes to what a console tool says to the model, and one to how it reports a mistake.

Every tool now says what it returns, and its text is one object

Each tool's text is a ToolText — summary, usage, coding, args, returns — from which the description is rendered, while args becomes the per-argument text in the JSON schema. Previously the description was a constant and the argument text a docstring beside the function, so a host could override one and not the other.

The Returns: half did not exist before. 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).

profile="agent"

execute carried 2501 characters of coding-agent guidance — git safety, package managers, what to do after three failed attempts — on every request, whether or not the workspace was a checkout. That is now the coding half of the text, kept under the default profile="coding" and dropped under "agent": about 240 tokens a request across the seven tools a typical host registers.

ModelRetry for a mistake the model can fix

A missing file, an offset past the end, an absent or ambiguous old_string, a stale read, a hashline hash that no longer matches — all of these used to come back as a string indistinguishable from a real answer. They are retry prompts now.

What stays a returned string is as deliberate: a non-zero exit from execute is a result, 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.

max_retries becomes a floor as well as a ceiling: on a tool's last attempt the message is returned rather than raised, so a model that mistypes an old_string twice can no longer end the run with UnexpectedModelBehavior. max_retries=0 reproduces the old behaviour entirely.

Also

descriptions accepts a ToolText as well as a string, and an unknown key raises UserError instead of being ignored.

Full detail in CHANGELOG.md.