An agent revises a scratchpad document in place with patch, which replaces an exact span of it or adds to its end and is offered wherever show is, on every call; a document too long for one reply goes in parts, show its start and patch the rest on; a compaction leaves a long patch out for a pointer as it does a shown document; the live session that measures it runs under a window four times its first prompt; and, since that session cost more with the scratchpad, an agent uses it only when the person asks for a document or the answer would run past about 80 lines, and answers in the reply otherwise¶
Decision 895 · accepted · 2026-10-13 · issue #616 · supersedes 870
What changed.
patch.name,new_stringand an optionalold_string. Withold_string, which must appear in the document exactly once, that span is replaced; with none,new_stringis added to the end, on a line of its own when neither side has the newline. The rule isedit_file's, the one models already know, and like it a span that is not there, or is there twice, is refused in a sentence that says what to do (read the document back withread_file; give more of the text around it). Each revision is the document's next version, ascratch_updatedlike ashow's, under the same lock, with the document's title and kind kept and thepatchcall as itscall_id, so a client's listing and panel show the whole document revised and the terminal UI puts its card where the call was. The size cap isshow's. A name the session has not shown is refused:patchrevises, it never creates.- Offered wherever
showis, on every call. A built-in, gated by nothing, in theplanagent's list besideshow, and:auto, since it writes only the session's own scratchpad. The tools are the front of every prompt, so a tool that came and went would change it (Decisions 867 and 870). - A long document goes in parts. Not a larger output budget for such a call: which
call will carry a long document is not known before the model writes it, and raising the
default
max_tokensfor every call is a change to every session's worst case, not this issue's. Ashoworpatchcall the output cap cut mid-argument (Decision 659 answers it rather than running it) is now answered with how: show the start, then add the rest withpatchand noold_string, one part a call. Each part is a reply of its own, so no part meets the cap, and the scratchpad holds the whole document.patch's description says an append is how a long document goes in parts. - A compaction and a patch. A
patchcall whoseold_stringandnew_stringare longer than its pointer is left out as ashowcall's words are:new_stringbecomes the pointer (name, version, size and the calls that read and revise it; a patch names no title) andold_string[left out since a compaction]. A shorter patch stays as it was, since its pointer would be the longer of the two. From the call's own arguments and result alone, so the pointer comes out the same however many compactions keep it, and with 878's other rules unchanged: only at a compaction, not a call the model has not replied after, not a refused one.
The issue's measure is not met. The session with the scratchpad cost 51% and 33% more over the run, and 81% and 27% more from its first compaction.
When an agent uses the scratchpad. Decided by the maintainer on 2026-10-13, from these
runs, and the issue closes with it: the scratchpad is not the default place for an
answer. An agent puts output there only when the person asks for a document (a plan,
report, table or diagram they want to keep or revise) or when the answer would run past
about 80 lines; every other answer goes in the reply, as before the scratchpad. A
document already there is revised with patch. This replaces 870's "a plan, report,
comparison, diagram or table they will read goes to show", which sent every plan there
whatever its length or whether anyone asked: in the runs above a session that did so cost
51% and 33% more over the run, and 81% and 27% more from its first compaction, because a
document costs a call of its own, a reply after it and a read back after each
compaction, and patches did not make a broad revision cheaper than writing it again.
- The words.
build.md: answer in the reply unless they ask for a document or the answer would run past about 80 lines, thenshow, a short reply naming it, andpatchto revise it.plan.mdsays the same of a plan.show's description says it in one sentence ("only when they ask for one ... or the answer would run past about 80 lines; otherwise answer in the reply"). At 80 lines, the threshold the maintainer named, the live session's plans (146 to 163 lines) are past it and its checklists (51 to 54 lines) are not, unless the person asks for one to keep.patch's description is unchanged. - The tools stay on every call.
showandpatchare still offered on every call of every agent that has them; only the words say when, since a tool that came and went would change the front of every prompt.
Governs: apps/troupe_core/lib/troupe/tools/patch.ex, apps/troupe_core/lib/troupe/tools/show.ex, apps/troupe_core/lib/troupe/scratch.ex