An agent with every tool is offered the task list only once its turn has made ten model calls or while there is a list, so a small task takes no calls for one; plan and workflow have it always.¶
Decision 793 · accepted · 2026-10-05 · issue #428
Superseded in part
In part by 867.
- Words were not enough. The first change was words only:
build.md,implementer.mdand the tool's description said a list is for work of more than five steps, and that for five or fewer the work is done without one, and "calltodo_writefirst" was gone. The model writes a list when it has the tool. - So the harness decides when it has the tool.
Troupe.Tools.available/2leavestodo_writeandtodo_readout of the tools a profile with every tool (build,general,implementer, a person's own agent with notools:list) is offered until its turn has made ten model calls, a subagent's included as the turn's line counts them (Tool.Ctx.turn_calls), unless there is a list, written earlier or added by a person in a client. A profile that names them in itstools:, asplanandworkflowdo, has them on every call: the list is what those are for. A call to the tool while it is not offered still runs, as the profile allows it, and the list it writes keeps the tool offered. Ten because no task of the suite took more than nine calls without its list (eight tool calls and the answer, in both runs), so none of them is offered one, and because a turn past ten calls is work long enough that the list carries what the conversation may lose and what a person watches the work by. A turn starts counting again: one with no list starts without the tool. - The words follow the tool.
build.mdsaystodo_writeis offered once the work has run long and what to do with it then; the tool's description says nothing of when a list is worth it, since it is only offered when one is;implementer.mdthe same asbuild.md. A prompt that names a tool the model does not have invites a call to it. - What it costs. The tools are the start of every prompt, so the call that first offers the list writes the whole prompt to the cache again, at most once a turn: on a turn of eleven calls or more with no list before it, or after a call to the tool unoffered. Every call before it is a little smaller (the two tools' definitions, about 1 kB). A long turn on a model that batches its updates with the work, as 777 asked, starts its list ten calls later than it could have.
- Not chosen. Answering a
todo_writethat only marks progress without a model round trip, or folding a lone one into the next call: by the time the harness reads a response holding only atodo_write, its call is spent, and the work it did not do needs the next call anyway; the harness could only stop counting it, which hides a call paid for, or rewrite the conversation afterwards, so that what was sent is not what the log replays and the cache is written again from that message on. Marking progress from the calls themselves: nothing in aread_fileor anedit_filesays which item it finishes, and a list marked by guesswork is worse than none for the person watching it. A bar in a number of steps alone: tried, above.
Governs: apps/troupe_core/lib/troupe/tools.ex, apps/troupe_core/lib/troupe/tool.ex, apps/troupe_core/lib/troupe/tools/todo.ex