[earakely-scale]

What and why

The shipped Claude Code agent served snapshot/v1's save and load, but not its changelog. So a run on it couldn't be rewound to a tool call and resumed there, which the wrapper this agent was ported from could do. This adds enable-changelog and apply-changelog.

• Capture:
  • enable-changelog installs a capture hook for both PostToolUse and PostToolUseFailure in the CLI's user settings.
  • After each tool call, whether it succeeded or failed, the hook archives that call's writes as a GNU incremental tar named <position:06d>.tgz, the position being the call's zero-based ordinal. It uploads the archive through the namespace grant with the protocol's NamespaceUploader.
  • Each archive also carries a small metadata file: the position, the tool call's session, and the capture roots removed since the last stored capture. The file lives in its own directory, outside every capture root.
  • The incremental state moves forward only once an archive is stored. If tar fails (exit 2 or more), an upload fails, or the grant's limits refuse an archive, the next archive carries those writes.
  • A reservation file keeps the grant's object and byte limits across hook processes.
  • enable-changelog refuses (409) while a turn runs. Once capture is on, turns run one at a time, so two contexts can't interleave in one sequence.
• Apply:
  • apply-changelog downloads the granted increments in order and refuses one that isn't a readable archive (422).
  • It extracts each increment at / with --incremental, so deletions replay too, and leaves the capture's metadata out of the extraction.
  • It replays the removed roots and drops any capture hook restored from the agent that captured.
  • With resume_conversation, it binds the target context to the transcript of the last applied tool call's session, under a fresh session id; a target already bound is rebound.
  • It refuses while a turn runs (409).
  • A snapshot load also drops restored capture hooks.
• Where: only on a host whose tar is GNU tar, which the image has. An install into Alpine or busybox serves the snapshot without the changelog.
• Changelog directory: one per port, outside every capture root, and 0700. It's refused if it's a link, not a directory, or owned by another user, since its config holds the grant.

The module is tar_changelog.py, not changelog.py, so it doesn't clash with the pi agent's changelog module when both load in one interpreter.

Known limitation: the hook runs before the CLI appends the tool call's result to the transcript. So increment k holds tool call k's writes but not its result, and a resumed conversation is missing the last applied call's result. The wrapper this agent was ported from behaves the same way. Fixing it means archiving at the next tool call, the turn's end or the CLI's exit, which is left for a follow-up.

How it was tested

• Unit tests: tst/unit/agents/claude_code/test_changelog.py covers:
  • capture:
    • a real hook process end to end, where each tool call's increment holds only its own writes and the replay restores the final state, deletions included;
    • a failed call taking its own position;
    • a failed tar, failed upload or refused upload leaving its writes to the next increment;
    • limits holding across hook processes;
  • metadata:
    • every capture archives its metadata;
    • a failed metadata write still captures;
    • deleting the CLI's state directory doesn't stop the capture of the other roots;
    • a user file with the metadata's name is restored;
  • apply:
    • removed roots replaying at any position, custom roots included;
    • resuming the last tool call's session over a larger transcript;
    • enable refusing while a turn runs, and a turn that arrives during enable being serialized;
    • the GNU tar gate and both cards;
    • directory refusal;
    • hook cleanup after an apply and after a snapshot load.
• Test runs:
  • The GNU tar tests skip on macOS and run on Linux. tst/unit/agents passes on Linux with GNU tar 1.35: 293 passed, 0 skipped.
  • CI's unit command passes on macOS: 9483 passed, 49 skipped. ruff check is clean.
• Live, on a dev deployment. The image was built from main (with fix(agents): open the 1M window for native-1M Claude models passed without [1m] #294) plus this branch, with the protocol pinned as a release pins it.

  • A2A validator: every check matches the agent this replaces, including the changelog's capture, apply and marker-read round trip.

  • Rewind to a tool call onto a fresh agent:

    • after three calls, the workspace holds exactly the first two calls' files;
    • when the middle call fails, the cut is still at the right call;
    • a capture root that a tool removed is gone after replay;
    • after a long conversation on one context and a tool call on another, the resumed agent continues the second.

    The wrapper failed the last three: it brought back the third call's file, kept the removed root, and resumed the wrong conversation.

  • Chaos battery against the agent it replaces, identical faults:

    • model 529, 500, reset and stall faults, a 401, the endpoint dropped mid-turn, the CLI and the container killed mid-turn, an install, a reinstall mid-turn, and an install killed mid-install;
    • the same outcome on every one, the next prompt passing, no CLI left running and no key in any output.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; the previous finding is fixed and no new actionable issues were found.

Summary

Adds Claude Code changelog capture and replay through snapshot/v1.

• Claude Code saves each tool call as an ordered changelog step.
• Claude Code can replay changelog steps and resume their conversation.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Tool[Tool call succeeds or fails] --> Hook[Capture hook]
  Hook --> Tar[GNU incremental tar]
  Tar --> Grant[Upload through namespace grant]
  Grant --> Apply[Apply granted increments]
  Apply --> Files[Restore writes and deletions]
  Apply --> Resume[Optionally bind restored conversation]

Loading

_{Reviews (4) · Last reviewed commit: "fix(agents): only treat the capture's re..." · Reviewed by Greptile}