akougkas.io

Why CLIO Coder, part 3 of 5: the agent writes its own handoff

CLIO Coder v0.5.2 turns compaction into a recoverable transaction: the agent writes its own handoff note with self_compact, the reduction leaves durable checkpoints, and an interrupted transition is resumed by an explicit operator command rather than guessed at.

Published
Reading
7 min read
Topics
agents, systems, building

A long session ends the same way in most coding agents: the window fills, something summarizes the history, and the work resumes a little dumber than it was. The summary is written by a process that was not doing the task, it is not addressed to anyone, and nothing records whether it survived. In CLIO Coder v0.5.2, released September 21, 2026, the agent doing the work writes the note, the reduction is a transaction with checkpoints, and an interruption in the middle of it is something an operator resolves by name.

Compaction as a transaction

The native orchestrator gets one tool for this, self_compact({"note_to_self": "…"}), and it must call it alone. A batch that pairs it with another tool, or asks for two compactions, is rejected before any valid sibling in that batch executes. The note is bounded at 8,192 UTF-8 bytes, must be nonblank, and is preserved exactly as written. Clio labels it assistant-authored recall, never an operator instruction, which matters because the text is about to be read back by a model that will otherwise treat anything at the top of its window as authority.

What the tool returns first is not a completed compaction. The first receipt means the note was prepared and flushed to the session ledger. Reduction happens after that receipt is persisted: the attempt is recorded before the summarizer is invoked, the outcome is checkpointed, and delivery intent is recorded before another foreground request is allowed. Acknowledgement is tied to a final, nonempty, successful assistant response. Intermediate tool calls, empty responses, errors, cancellation, and a generic end-of-run event do not acknowledge anything. Continuation preserves the original operator turn instead of appending a new one.

The whole transaction is bounded. Each handoff allows at most two reduction attempts, at most two summary stream invocations per attempt, and a fifteen-minute automatic window. A new operator recovery request can renew that window; it does not refund spent attempts or mint a replacement handoff identity. Summarizer calls, including failed ones with known usage, stay attributable to the session that made them.

The handoff cycle in CLIO Coder: an operator turn is admitted against a budget of estimated input plus reserved output, the agent writes a note with self_compact, the reduction records summary and eviction checkpoints, and the handoff either delivers the continuation, which returns to the same operator turn, or pauses for explicit recovery through the context recover command. operator turn budget check self_compact note summary checkpoint continuation /context recover
The handoff cycle: an admitted turn, a note the agent writes for itself, a checkpointed reduction, and either a delivered continuation of the same turn or a paused handoff awaiting an operator command.

Recovery is a command, not a guess

A process that restarts in the middle of a reduction records the interrupted state as paused. It does not repeat an uncertain delivery. The /context overlay shows the pending handoff identifier and its phase, and the operator resolves it with the exact identifier:

/context recover <handoffId> reduce
/context recover <handoffId> deliver

reduce is available when the handoff has not committed and an attempt remains; deliver is available when a validated commit exists. Authority to do either comes from the operator command and its durable control record, and it is bound to the branch that owns the handoff. It never comes from a tool argument or from text found inside a note, which closes the obvious path by which a model could write itself permission to resume. Missing or conflicting storage evidence prevents recovery rather than starting a fresh transaction under a new identity; a missing commit is reconstructed only from a validated summary carry, under its original reserved identity and an exact storage check.

Session format v5 keeps continuity records through replay, forks, export, and later summaries. A fork inherits the note as recall and does not inherit permission to resume the parent’s handoff. Ordinary summaries live in the session ledger and replay after /resume, so the continuity is a property of the recorded session rather than of a process that happened to stay alive.

The budget both sides can read

None of this works if the window is a surprise. Admission requires estimated input plus the resolved output reservation to fit the effective window, and it is checked at submission, at settled tool continuation, and again at the final provider boundary after steering has been drained. Pending user-message framing and images are priced. Disabling automatic compaction is a preference about routine pressure; it cannot authorize an oversized request. The operator reads the same accounting in /context that the model reads through context(scope="budget"), which removes the usual asymmetry where the agent negotiates against a limit only the harness can see.

Durable memory is frozen the same way. Approved selection is fixed for a prepared turn and its continuations, and a change in session, repository, runtime, model, or memory configuration invalidates that authority. Selection uses bounded content hashes, so a same-size rewrite of a record cannot hide behind a file-size cache key. The defaults stay five records and 400 estimated tokens, and lexical relevance ranking remains experimental and off. The roadmap names the reason these are separate mechanisms at all: three memory lifetimes, the active working set, session continuity, and reviewed durable lessons, each with explicit provenance and scope. CLIO Coder is experimental and pre-1.0, and token counts remain estimates unless a provider has attested the relevant prefix. This is the same argument I made about agent memory as a storage problem: lifetime and provenance are properties of the store, not of the prompt.

Try it

Install and start a session, then work until the window is under real pressure.

npm install -g @iowarp/clio-coder
clio-coder configure
clio-coder

Open the context ledger before and after a reduction. With no arguments it shows the window, the working-set policy, evicted items and tokens, and any pending handoff with its phase.

/context
/context compact

If a reduction is interrupted, the overlay names the handoff. Use the identifier it prints:

/context recover <handoffId> deliver

You will see the note the agent wrote to itself replayed as assistant-authored recall, and the original task continue without a second operator turn.

What is left for you

The open question is which reductions are worth what they cost. The roadmap is explicit that threshold changes and wider memory automation still depend on comparative evaluation across task completion, context cost, cache effects, and recovery latency together, and that evaluation is easier to do with sessions that are not mine. Long-running work on an unfamiliar repository, a slow local model, a provider that rate-limits mid-reduction: each of those stresses a different part of the transaction. Session ledgers and evidence bundles record enough to argue about, and issues at github.com/iowarp/clio-coder are where that argument belongs. The launch essay covers what “public” currently means for this project, and the GPU tutorial covers install depth.

Next in the series Part 4: Bounded workers, sealed receipts

Sources, code, and records

  1. source

    CLIO Coder v0.5.2 release

    Context continuity and memory, September 21, 2026: native self-compaction, explicit handoff recovery, enforced request budgets, and frozen durable-memory selection.

  2. source

    CLIO Coder repository

    Source, changelog, roadmap, and the shipped documentation for context continuity.

  • 2023–present
    active

    CLIO Coder

    A local-first coding agent with typed tools, bounded workers, and receipts

  • 2025–present
    active

    CLIO

    A context layer for scientific AI agents and workflows

More on CLIO Coder

  1. essay

    Reliable work from unreliable agents

    A coding agent is a system built around one brilliant, persuasive, unreliable component. The argument of my November 9, 2026 lecture on agentic engineering: five ideas for building trustworthy work around that component, what they could do for science, and the problems still open.

    14 min
  2. essay

    CLIO as the entry point

    CLIO should become the single place a developer starts with IOWarp, built as an application SDK with deployment profiles rather than an umbrella package or a gateway service. This is the direction for 2027; the API and the scope are still open.

    6 min
  3. essay

    A capable model in a capable harness

    Claude 3.5 Sonnet brought me back to writing code. A capable model still needs a harness that makes its progress checkable and its cost visible, and CLIO Coder is the one I built around models that many people can afford to use.

    4 min