# Handoff and compaction (the version-specific detail)

This file holds the material that rots fastest — the exact server-side compaction API
contract and the concrete templates. Re-verify the numbers against the live docs before you
quote them; they are dated, not eternal.

## Server-side compaction API contract

Source: Claude API "Compaction" docs, accessed 2026-06-02.

- **Beta header:** `compact-2026-01-12`
- **Edit type:** `compact_20260112`
- **Default trigger:** `trigger.type = "input_tokens"`, `trigger.value = 150000` (minimum allowed: `50000`)
- **`pause_after_compaction`:** defaults `false` (the model continues straight from the summary)

### Behaviour you must account for

1. When the trigger fires, the API emits a **compaction block** and **drops all blocks before it**, continuing from the `<summary>` it produced.
2. You must **append the whole response — including the compaction block — to subsequent requests.** If you strip the compaction block, the next request loses the summarised state. This is the easiest thing to get wrong.
3. The summary is generated by a default prompt that distils the prior turns into a `<summary>`; you can steer what it preserves the same way you steer a manual `/compact` (keep decisions, paths, TODOs).

### Minimal request shape (illustrative)

```json
{
  "betas": ["compact-2026-01-12"],
  "context_management": {
    "edits": [
      {
        "type": "compact_20260112",
        "trigger": { "type": "input_tokens", "value": 150000 },
        "pause_after_compaction": false
      }
    ]
  }
}
```

Treat the field names as version-stamped: the `compact_20260112` suffix *is* the version. When
the beta graduates or revs, this block changes — do not assume it.

## Progress-file template

Drop this in the workspace (e.g. `claude-progress.txt` or `PROGRESS.md`) and rewrite it before
you run low on window. A fresh session should resume from this in a single read.

```markdown
# Progress: <task name>

## Goal
<one or two sentences — what "done" looks like>

## Done
- <unit completed> — proof: <commit hash / file path / test name>
- ...

## In progress
- <the one unit currently open> — current state: <where it stands>

## Next
1. <the very next concrete step>
2. <then this>

## Gotchas / constraints
- <non-obvious thing that will bite a fresh window>
- <decision that must not be relitigated, and why>

## Key paths
- <path:line> — <what lives there>
- ...
```

Rules:

- **One unit at a time.** Close a unit, record its proof (a commit hash beats a paragraph), then open the next.
- **Proof over prose.** "Done: auth migration — commit a1b2c3d, tests in auth/migrate.test.ts" beats three paragraphs describing it.
- **Write it before you need it.** A handoff written at 60% is calm and complete; one scrambled at 97% is missing the gotchas.

## Good vs. bad summary checklist

A summary (manual `/compact`, server-side, or a handoff note) is judged by one question:
**can a fresh window resume the task from it alone?**

**Keep (load-bearing):**

- Decisions made, and the one-line reason for each.
- Every file path touched, with `path:line` where it matters.
- Open TODOs and the next concrete step.
- Constraints and gotchas a fresh window can't re-derive.

**Drop (noise):**

- Raw tool logs and full command output.
- Dead-end exploration ("tried X, didn't work" collapses to one line, not the transcript).
- Redundant restatements of things already captured.
- Pleasantries and meta-commentary about the process.
