@misterhuydo/cairn-mcp 1.18.0 → 1.20.0

package/README.md

@@ -50,10 +50,11 @@ server load.
 | Hook | Trigger | Effect |
 |---|---|---|
 | `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline with **line numbers** to save tokens |
-| `PreToolUse[Edit]` | Every file edit | Blocks Edit if Claude only saw compressed content — requires a full re-read first |
+| `PreToolUse[Edit]` | Every file edit | Blocks Edit if Claude only saw compressed content — requires a full re-read first. Reported as a permission decision with a one-line reason, **not** as a red hook error: being sent back to re-read a file is a normal step, and the full source rides along out of sight so it does not fill the screen |
 | `PostToolUse[ExitPlanMode]` | A plan is approved | The plan is parsed into `### Phase N` entries in `.cairn/roadmap.md`, synced, and the cursor activated |
 | `PostToolUse[TodoWrite]` | The todo list changes | Todos mirror onto the roadmap as sub-tasks under the current phase (or seed root phases if none exist) |
-| `Stop` | End of every response | Session auto-saved to `.cairn/session.json`, Claude auto-memory backed up to `.cairn/memory/`, the roadmap re-surfaced, and any git-detected completed phases surfaced for you to confirm — all in one line |
+| `Stop` | End of every response | Session auto-saved to `.cairn/session.json`, Claude auto-memory backed up to `.cairn/memory/`, the roadmap re-surfaced, any git-detected completed phases surfaced for you to confirm, and — once the session is genuinely large — a prompt asking whether you want to `/clear` or `/compact`, with a recommendation and the reason. All in one line |
+| `SessionStart[clear]`<br>`SessionStart[compact]` | Right after you `/clear` or `/compact` | The checkpoint is re-injected into the fresh session automatically, so it opens already knowing the open thread and what the last session would have lost. You do not have to type "resume" |
 | `UserPromptSubmit` | First message of a new session | Fresh project: Claude prompted to run `cairn_maintain`. Returning session: Claude prompted to run `cairn_resume`. Memory restored from `.cairn/memory/` if the Claude store is empty (new machine / fresh clone) |
 
 ---
@@ -83,7 +84,7 @@ No manual steps. The index lives in `.cairn/index.db` inside your project — li
 | `cairn_todos` | Scan codebase for TODO/FIXME/HACK comments, add manual items, resolve and list them |
 | `cairn_roadmap` | The active project plan: phases authored in `.cairn/roadmap.md`, with a cursor, dependencies, and auto-pruning of shipped phases into `.cairn/roadmap_completed.md` |
 | `cairn_bundle` | Minified source snapshot (auto-handled by hooks) |
-| `cairn_checkpoint` | Save session state (auto-handled by hooks) |
+| `cairn_checkpoint` | Save session state (auto-handled by hooks). At a stopping point, answer `would_be_lost` — the one part that git and the index cannot recover |
 | `cairn_minify` | Minify a single file on demand (fallback when hooks are not installed) |
 | `cairn_switch` | Switch active project root mid-session (use for maintenance on a sibling service) |
 | `cairn_memo` | Save a preference, decision, or discovery to the project's persistent memory |
@@ -236,6 +237,86 @@ before calling `set_status … done`, so a stray keyword can't silently prune yo
 
 ---
 
+## Stopping points: what clearing would cost
+
+Before `/clear` or `/compact`, the question that actually matters is not *how full
+is the window*. Fullness tells you **when**; it never tells you **which**. What
+decides it is whether the saved state is sufficient — "the slice is three-quarters
+built and the fact that long-press selection has never run on a real handset is
+written down nowhere" is a judgement about the handoff, not about a percentage.
+
+Cairn cannot make that judgement for you. It cannot audit for absence: the gap
+worth reporting is by definition the thing nobody wrote down, and a lazy
+checkpoint looks exactly like a thorough one from the outside. A tool that
+computed this would print "nothing outstanding" on precisely the sessions where
+the most was outstanding. So cairn does the part it can do honestly — it **demands
+the judgement on the way in and carries it across the gap**:
+
+1. **`cairn_checkpoint` asks.** A `would_be_lost` field whose description is the
+   literal question: what would a fresh session not know? Unverified work, a
+   thread you are mid-way through, a decision whose reason never made it into the
+   commit message. A checkpoint that skips it says so in its result rather than
+   passing silently.
+2. **`cairn_resume` carries it back**, near the top of the payload and first in
+   the summary, because everything else resume returns is recoverable from git and
+   the index and this is the only part that is not. It also lands on the first
+   prompt of the next session, since a session picked up after `/clear` rarely
+   opens with the word "resume".
+3. **It ages.** The end-of-turn hook checkpoints every turn, so `session.json`
+   always *looks* fresh while its contents may be hours and several slices stale.
+   The handoff is stamped only when it is actually written, never by the
+   heartbeat that copies it forward, and anything written before commits that
+   have since landed is reported as possibly stale.
+4. **Then, and only then, it asks.** When the session crosses the threshold **and**
+   something is actually at risk, the Stop hook asks you to choose, with a
+   recommendation and the reason:
+
+   > **Checkpoint + /clear (Recommended)** — I write the handoff now, then you type `/clear`
+   > **Checkpoint + /compact** — I write the handoff now, then you type `/compact`
+   > **Keep going** — decline
+
+   Which one is recommended follows from the handoff, not from fullness. A
+   *current* handoff means the thread survives a hard reset, so `/clear` wins and
+   you get the full window back. A *missing or stale* one means something unwritten
+   is at risk, so `/compact` wins and keeps it reachable. Either choice writes the
+   checkpoint first — including `/clear`, which needs it most, not least.
+
+5. **And it is there afterwards.** `SessionStart[clear|compact]` re-injects the
+   checkpoint into the fresh session, so it opens already knowing where it is. You
+   never have to remember to type "resume", which is exactly the manual step that
+   gets skipped on the sessions where skipping it costs the most.
+
+**Cairn cannot type the command.** No hook output and no tool can trigger a slash
+command, so the agent does the half it can do (the checkpoint, immediately) and you
+type the six characters. Anything that claimed otherwise would leave you waiting for
+something that never happens.
+
+### How the size is measured
+
+Not from file size. No hook input carries token counts, but every hook receives
+`transcript_path`, and the transcript's assistant records carry the usage the API
+actually reported — so cairn tail-reads the last 256 KB and sums the real window
+(input + cache reads + cache creation + output). Measured cost: 6 lines parsed,
+0.5 ms.
+
+v1.19.0 used transcript bytes as the proxy and it was wrong in the one place that
+mattered. Measured on cairn's own session: **3.40 MB of transcript holding 72,285
+tokens of context.** Bytes keep accumulating across a `/compact` while the window
+resets, so a byte threshold is loudest immediately *after* a compaction, when there
+is least reason to speak. Bytes survive now only as a fallback for when no usage
+record is reachable, and when that happens the line says so instead of dressing a
+file size up as a token count.
+
+Deliberately not built: no percentage (the context-window size is not observable
+from a hook, so the denominator would be invented — the absolute count is reported
+instead), no full transcript walk (the tail only; a full walk in this hot path once
+froze every terminal in the cockpit for 4.3 seconds), no counting subagent spend as
+main-thread context, no repeating the prompt when nothing changed, and no
+auto-clearing, auto-compacting, or filling the field in on your behalf. Same shape
+as completed-phase detection: detect, surface, confirm with the user, never apply.
+
+---
+
 ## Supported languages
 
 | Language | What Cairn extracts |