@misterhuydo/cairn-mcp 1.19.0 → 1.20.0

package/README.md

@@ -53,7 +53,8 @@ server load.
 | `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, any git-detected completed phases surfaced for you to confirm, and on a long session one line naming what clearing would cost — 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) |
 
 ---
@@ -266,19 +267,53 @@ the judgement on the way in and carries it across the gap**:
    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, one line.** When the session transcript crosses a coarse
-   size threshold **and** something is actually at risk, the Stop hook adds a line
-   naming the loss: *"Clearing now would lose: … — last written before the 3
-   commits since."* When the handoff is current it says what clearing costs
-   instead, which is the more useful message and the one that lets you actually
-   clear.
-
-Deliberately not built: no percentage (the transcript keeps growing across a
-compaction while the window resets, so a precise number would claim an accuracy
-it does not have), no transcript parsing (`statSync` only — this runs on every
-single turn), no repeating the line 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.
+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.
 
 ---