v0.6.0 (beta)

thunc 0.6.0 settles agents. The agent API is frozen: from here on it changes only through deprecations, and a test of every public signature keeps it so. The run record carries a format number, as the events always have, and both, like durable task fingerprints, now have a written compatibility promise. A program written for 0.5 runs unchanged.

pip install --upgrade thunc

The frozen API

• thunc.Agent and its methods, @thunc.agent, thunc.Run and thunc.AgentError are frozen. tests/api.txt lists them, and the rest of thunc.__all__ and thunc.testing, signature by signature, and a test fails on any difference. Additions are made freely; a removal or a change goes through a deprecation of at least two minor releases.
• New before the freeze: agent.acall, agent.call to await. Agent(protocol=...) and Agent(effort=...) are typed as their Literal choices.
• thunc write stays experimental through 1.0, outside the freeze.

Formats with a promise (the API docs)

• An agent run's record has "format": 1 on its start line, as each THUNC_EVENTS line has "v": 1. Within one format, both only gain events and fields; a change an old reader would misread gets a new number. The docs list every line and field, and a test checks that what thunc writes matches them. thunc watch skips a record in a format it doesn't know, from the next thunc-watch release.
• Durable task fingerprints: upgrading thunc doesn't change the fingerprint of a task registered the same way, so runs in flight survive a thunc upgrade. A test pins the fingerprints of four task shapes; they're the same as 0.3.2's, checked against a checkout of it.

Measured (the tool-use benchmark, deep_fix, Claude Opus 5.5 on Claude Code, 3 runs each)

Default read	Turns	Seconds	$ per run
400 lines (kept)	8	17	0.092
1,000 lines	8	17	0.127
The whole 2,000-line file	4	11	0.181

Only reading the whole file cuts the turns, and it doubles the cost, so read keeps giving 400 lines unless the model asks for more. The two Codex items stay open: codex exec --json marks no model reply, so steps on native Codex runs count tool calls, and it reports tokens only when a turn ends, which a native run never reaches.

Tested

• Offline tests on Python 3.10–3.14 on Ubuntu, and on Windows, with new tests for the run record's and the events' fields, the fingerprints, the public API snapshot (the same on 3.10, 3.13 and 3.14) and agent.acall. thunc watch's tests cover skipping a newer record.

Behavior changes

• An agent run's record has a new format field on its first line. Readers that ignore unknown fields, as thunc watch does, see no change.

Full changelog: v0.5.0...v0.6.0