@isaacriehm/cairn-core 0.10.4 → 0.11.0

package/dist/hooks/runners/context-threshold.d.ts

@@ -8,16 +8,16 @@
  * `decision: block` with an instructional reason that prompts main
  * Claude to render the question.
  *
- * Threshold defaults to 50 % of the active model's window:
- *   - claude-opus-*    → 1_000_000 tokens, fire at 500_000
- *   - claude-sonnet-*  →   200_000 tokens, fire at 100_000
- *   - claude-haiku-*   →   200_000 tokens, fire at 100_000
- *   - unknown model    → assume Opus shape (1M / 500k threshold)
+ * Single source of truth: Claude Code's statusline payload ships a
+ * `context_window` block with `total_tokens` (the active model's
+ * window — 200k Sonnet, 1M Opus-1m) + `remaining_percentage`. The
+ * statusline hook persists those numbers to
+ * `.cairn/sessions/<id>/ctx.json` on every prompt. The Stop hook reads
+ * that snapshot — there is no model-keyed fallback and no transcript-
+ * usage estimator. If CC omits the block, ctx.json is absent or stale
+ * and the threshold check stays silent rather than firing on a guess.
  *
- * Token count is estimated from the transcript file size (`bytes / 4`)
- * — overcounts a little on JSON whitespace, undercounts on unicode-
- * heavy turns. Good enough to fire near the threshold; not a budget
- * check.
+ * Threshold defaults to 50 % of CC's reported window.
  *
  * Suppress re-fire within the same session by stamping
  * `.cairn/sessions/<id>/ctx-threshold-warned.json`. Once stamped, the
@@ -25,54 +25,22 @@
  * past the last warning.
  */
 export interface ContextThresholdInput {
-    transcriptPath: string | null;
     repoRoot: string;
     sessionId: string;
-    /** Override the model lookup (rarely needed). */
-    modelOverride?: string | null;
     /** Override the threshold fraction (default 0.5). */
     thresholdFraction?: number;
-    /** Override the window size in tokens (default keyed on model). */
-    windowOverride?: number;
 }
 export interface ContextThresholdHit {
     hit: true;
-    estimatedTokens: number;
+    usedTokens: number;
     windowTokens: number;
     pct: number;
-    model: string;
     taskId: string | null;
 }
 export interface ContextThresholdMiss {
     hit: false;
 }
 export type ContextThresholdResult = ContextThresholdHit | ContextThresholdMiss;
-export declare function modelWindow(model: string): number;
-/**
- * Walk the last ~64 KB of the transcript looking for the most recent
- * `model` field. Claude Code transcript lines are JSON; each assistant
- * turn carries a `message.model` string. Skipping the full file keeps
- * the hook fast on long sessions.
- */
-export declare function readModelFromTranscript(path: string): string | null;
-/**
- * Fallback estimator when no persisted ctx snapshot is available.
- *
- * Walks the last ~256 KB of the transcript backward looking for the
- * most recent `message.usage` block from an assistant turn. Claude
- * Code transcript lines are JSON; assistant turns carry an exact token
- * count under `message.usage.{input_tokens, cache_creation_input_tokens,
- * cache_read_input_tokens}` — summing those three gives the actual
- * prompt size at that turn (output_tokens are produced, not consumed
- * by context).
- *
- * Returns null when no usage block is found (e.g. fresh session, no
- * assistant turn yet). Caller can choose to skip threshold check or
- * fall back to bytes/4. We never fall back here — bytes/4 over-counts
- * 1.5–2x because the transcript JSONL accumulates every tool I/O blob
- * since session start, which is what produced the 113%-of-window bug.
- */
-export declare function estimateTokensFromTranscript(transcriptPath: string): number | null;
 /**
  * Returns the current threshold result. Stamps the warned-state file
  * on a hit so re-fires within the same session are suppressed until

package/dist/hooks/runners/context-threshold.js

@@ -8,79 +8,31 @@
  * `decision: block` with an instructional reason that prompts main
  * Claude to render the question.
  *
- * Threshold defaults to 50 % of the active model's window:
- *   - claude-opus-*    → 1_000_000 tokens, fire at 500_000
- *   - claude-sonnet-*  →   200_000 tokens, fire at 100_000
- *   - claude-haiku-*   →   200_000 tokens, fire at 100_000
- *   - unknown model    → assume Opus shape (1M / 500k threshold)
+ * Single source of truth: Claude Code's statusline payload ships a
+ * `context_window` block with `total_tokens` (the active model's
+ * window — 200k Sonnet, 1M Opus-1m) + `remaining_percentage`. The
+ * statusline hook persists those numbers to
+ * `.cairn/sessions/<id>/ctx.json` on every prompt. The Stop hook reads
+ * that snapshot — there is no model-keyed fallback and no transcript-
+ * usage estimator. If CC omits the block, ctx.json is absent or stale
+ * and the threshold check stays silent rather than firing on a guess.
  *
- * Token count is estimated from the transcript file size (`bytes / 4`)
- * — overcounts a little on JSON whitespace, undercounts on unicode-
- * heavy turns. Good enough to fire near the threshold; not a budget
- * check.
+ * Threshold defaults to 50 % of CC's reported window.
  *
  * Suppress re-fire within the same session by stamping
  * `.cairn/sessions/<id>/ctx-threshold-warned.json`. Once stamped, the
  * threshold prompt re-fires only when usage climbs another +10 %
  * past the last warning.
  */
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-const MODEL_WINDOW_FALLBACK = 1_000_000;
-export function modelWindow(model) {
-    // Opus 4.7 ships with a 1M-token window when the `[1m]` variant is
-    // selected; the base alias still resolves to 200k. Treat any model
-    // string that contains `1m` (the variant suffix Claude Code prints)
-    // as the 1M tier so the statusline percentage reads correctly.
-    if (/1m/i.test(model))
-        return 1_000_000;
-    if (/opus/i.test(model))
-        return 1_000_000;
-    if (/sonnet/i.test(model))
-        return 200_000;
-    if (/haiku/i.test(model))
-        return 200_000;
-    return MODEL_WINDOW_FALLBACK;
-}
-/**
- * Walk the last ~64 KB of the transcript looking for the most recent
- * `model` field. Claude Code transcript lines are JSON; each assistant
- * turn carries a `message.model` string. Skipping the full file keeps
- * the hook fast on long sessions.
- */
-export function readModelFromTranscript(path) {
-    try {
-        const stat = statSync(path);
-        const tail = Math.min(stat.size, 65_536);
-        const fd = readFileSync(path, "utf8");
-        const slice = fd.slice(Math.max(0, fd.length - tail));
-        const lines = slice.split(/\r?\n/);
-        for (let i = lines.length - 1; i >= 0; i--) {
-            const line = lines[i];
-            if (line === undefined || line.length === 0)
-                continue;
-            try {
-                const obj = JSON.parse(line);
-                const m = obj.message?.model;
-                if (typeof m === "string" && m.length > 0)
-                    return m;
-            }
-            catch {
-                // skip malformed lines
-            }
-        }
-    }
-    catch {
-        return null;
-    }
-    return null;
-}
 const CTX_SNAPSHOT_STALE_MS = 5 * 60 * 1000;
 /**
  * Read the latest persisted ctx snapshot from the statusline writer.
  * Statusline runs on every prompt so a fresh snapshot is normally
  * <1s old. Returns null when missing, malformed, or older than 5min
- * (e.g. session crashed, statusline hook misconfigured).
+ * (e.g. session crashed, statusline hook misconfigured, or CC did
+ * not ship a `context_window` block on the last prompt).
  */
 function readPersistedCtx(repoRoot, sessionId) {
     const path = join(repoRoot, ".cairn", "sessions", sessionId, "ctx.json");
@@ -92,6 +44,8 @@ function readPersistedCtx(repoRoot, sessionId) {
             parsed !== null &&
             typeof parsed.usedPct === "number" &&
             typeof parsed.usedTokens === "number" &&
+            typeof parsed.windowTokens === "number" &&
+            parsed.windowTokens > 0 &&
             typeof parsed.ts === "number") {
             if (Date.now() - parsed.ts > CTX_SNAPSHOT_STALE_MS)
                 return null;
@@ -103,60 +57,6 @@ function readPersistedCtx(repoRoot, sessionId) {
     }
     return null;
 }
-/**
- * Fallback estimator when no persisted ctx snapshot is available.
- *
- * Walks the last ~256 KB of the transcript backward looking for the
- * most recent `message.usage` block from an assistant turn. Claude
- * Code transcript lines are JSON; assistant turns carry an exact token
- * count under `message.usage.{input_tokens, cache_creation_input_tokens,
- * cache_read_input_tokens}` — summing those three gives the actual
- * prompt size at that turn (output_tokens are produced, not consumed
- * by context).
- *
- * Returns null when no usage block is found (e.g. fresh session, no
- * assistant turn yet). Caller can choose to skip threshold check or
- * fall back to bytes/4. We never fall back here — bytes/4 over-counts
- * 1.5–2x because the transcript JSONL accumulates every tool I/O blob
- * since session start, which is what produced the 113%-of-window bug.
- */
-export function estimateTokensFromTranscript(transcriptPath) {
-    try {
-        const stat = statSync(transcriptPath);
-        const tail = Math.min(stat.size, 262_144);
-        const fd = readFileSync(transcriptPath, "utf8");
-        const slice = fd.slice(Math.max(0, fd.length - tail));
-        const lines = slice.split(/\r?\n/);
-        for (let i = lines.length - 1; i >= 0; i--) {
-            const line = lines[i];
-            if (line === undefined || line.length === 0)
-                continue;
-            try {
-                const obj = JSON.parse(line);
-                const u = obj.message?.usage;
-                if (u === undefined)
-                    continue;
-                const i_t = typeof u.input_tokens === "number" ? u.input_tokens : 0;
-                const cc = typeof u.cache_creation_input_tokens === "number"
-                    ? u.cache_creation_input_tokens
-                    : 0;
-                const cr = typeof u.cache_read_input_tokens === "number"
-                    ? u.cache_read_input_tokens
-                    : 0;
-                const total = i_t + cc + cr;
-                if (total > 0)
-                    return total;
-            }
-            catch {
-                // skip malformed lines
-            }
-        }
-    }
-    catch {
-        return null;
-    }
-    return null;
-}
 function warnedStatePath(repoRoot, sessionId) {
     return join(repoRoot, ".cairn", "sessions", sessionId, "ctx-threshold-warned.json");
 }
@@ -192,39 +92,28 @@ function writeWarned(repoRoot, sessionId, state) {
  * usage climbs another +10 % of the window.
  */
 export function checkContextThreshold(input) {
-    if (input.transcriptPath === null || input.transcriptPath.length === 0) {
-        return { hit: false };
-    }
-    if (!existsSync(input.transcriptPath))
+    const snapshot = readPersistedCtx(input.repoRoot, input.sessionId);
+    if (snapshot === null)
         return { hit: false };
-    const model = input.modelOverride ?? readModelFromTranscript(input.transcriptPath) ?? "unknown";
-    const windowTokens = input.windowOverride ?? modelWindow(model);
+    const windowTokens = snapshot.windowTokens;
     const fraction = input.thresholdFraction ?? 0.5;
     const thresholdTokens = Math.floor(windowTokens * fraction);
-    const snapshot = readPersistedCtx(input.repoRoot, input.sessionId);
-    const fallback = estimateTokensFromTranscript(input.transcriptPath);
-    // Skip the check when neither source is available — better to stay
-    // silent than fire on bytes/4 garbage like we used to.
-    if (snapshot === null && fallback === null)
-        return { hit: false };
-    const estimated = snapshot !== null ? snapshot.usedTokens : (fallback ?? 0);
-    if (estimated < thresholdTokens)
+    if (snapshot.usedTokens < thresholdTokens)
         return { hit: false };
     const warned = readWarned(input.repoRoot, input.sessionId);
     const reFireSlackTokens = Math.floor(windowTokens * 0.1);
-    if (warned !== null && estimated < warned.warned_at_tokens + reFireSlackTokens) {
+    if (warned !== null && snapshot.usedTokens < warned.warned_at_tokens + reFireSlackTokens) {
         return { hit: false };
     }
     writeWarned(input.repoRoot, input.sessionId, {
         ts: Date.now(),
-        warned_at_tokens: estimated,
+        warned_at_tokens: snapshot.usedTokens,
     });
     return {
         hit: true,
-        estimatedTokens: estimated,
+        usedTokens: snapshot.usedTokens,
         windowTokens,
-        pct: Math.min(100, Math.round((estimated / windowTokens) * 100)),
-        model,
+        pct: Math.min(100, Math.round((snapshot.usedTokens / windowTokens) * 100)),
         taskId: null,
     };
 }
@@ -242,7 +131,7 @@ export function renderContextThresholdHint(hit, taskId) {
     const header = [
         `## Cairn — context threshold reached`,
         "",
-        `Estimated **${hit.estimatedTokens.toLocaleString()} / ${hit.windowTokens.toLocaleString()} tokens (${hit.pct}%)** for \`${hit.model}\`. Trust degrades as context climbs — best to compact now.`,
+        `**${hit.usedTokens.toLocaleString()} / ${hit.windowTokens.toLocaleString()} tokens (${hit.pct}%)** in use. Trust degrades as context climbs — best to compact now.`,
         "",
     ];
     if (taskId === null) {
@@ -252,7 +141,7 @@ export function renderContextThresholdHint(hit, taskId) {
             "",
             "Render this question via the `AskUserQuestion` tool — do not skip:",
             "",
-            "> Context at " + hit.pct + "% of " + hit.model + " window. Pick:",
+            "> Context at " + hit.pct + "% of window. Pick:",
             "> ",
             "> - `[a]` keep going (warn re-fires every +10 %)",
             "> - `[b]` `/clear` and start fresh (no task to resume)",
@@ -266,7 +155,7 @@ export function renderContextThresholdHint(hit, taskId) {
         "",
         "Render this question via the `AskUserQuestion` tool — do not skip:",
         "",
-        "> Context at " + hit.pct + "% of " + hit.model + " window. Pick:",
+        "> Context at " + hit.pct + "% of window. Pick:",
         "> ",
         "> - `[a]` keep going (warn re-fires every +10 %)",
         "> - `[b]` `/clear` and resume now (Cairn writes the resume prompt)",

package/dist/hooks/runners/context-threshold.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-threshold.js","sourceRoot":"","sources":["../../../src/hooks/runners/context-threshold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA6BjC,MAAM,qBAAqB,GAAG,SAAS,CAAC;AAExC,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,mEAAmE;IACnE,mEAAmE;IACnE,oEAAoE;IACpE,+DAA+D;IAC/D,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzC,MAAM,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACtD,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAqC,CAAC;gBACjE,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC;gBAC7B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;oBAAE,OAAO,CAAC,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAQD,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE5C;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,QAAgB,EAAE,SAAiB;IAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACzE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;QACrE,IACE,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;YAClC,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ;YACrC,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,EAC7B,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,EAAE,GAAG,qBAAqB;gBAAE,OAAO,IAAI,CAAC;YAChE,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,4BAA4B,CAAC,cAAsB;IACjE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC1C,MAAM,EAAE,GAAG,YAAY,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACtD,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAQ1B,CAAC;gBACF,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC;gBAC7B,IAAI,CAAC,KAAK,SAAS;oBAAE,SAAS;gBAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;gBACpE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,2BAA2B,KAAK,QAAQ;oBAC1D,CAAC,CAAC,CAAC,CAAC,2BAA2B;oBAC/B,CAAC,CAAC,CAAC,CAAC;gBACN,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,uBAAuB,KAAK,QAAQ;oBACtD,CAAC,CAAC,CAAC,CAAC,uBAAuB;oBAC3B,CAAC,CAAC,CAAC,CAAC;gBACN,MAAM,KAAK,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,CAAC;gBAC5B,IAAI,KAAK,GAAG,CAAC;oBAAE,OAAO,KAAK,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AASD,SAAS,eAAe,CAAC,QAAgB,EAAE,SAAiB;IAC1D,OAAO,IAAI,CACT,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,SAAS,EACT,2BAA2B,CAC5B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,QAAgB,EAAE,SAAiB;IACrD,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAClD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;QACrE,IACE,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ;YAC7B,OAAO,MAAM,CAAC,gBAAgB,KAAK,QAAQ,EAC3C,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAClB,QAAgB,EAChB,SAAiB,EACjB,KAAkB;IAElB,IAAI,CAAC;QACH,aAAa,CACX,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,EACpC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EACrC,MAAM,CACP,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,cAAc;IAChB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAA4B;IAE5B,IAAI,KAAK,CAAC,cAAc,KAAK,IAAI,IAAI,KAAK,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IACxB,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAE7D,MAAM,KAAK,GACT,KAAK,CAAC,aAAa,IAAI,uBAAuB,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,SAAS,CAAC;IACpF,MAAM,YAAY,GAAG,KAAK,CAAC,cAAc,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,KAAK,CAAC,iBAAiB,IAAI,GAAG,CAAC;IAChD,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;IAE5D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IACnE,MAAM,QAAQ,GAAG,4BAA4B,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACpE,mEAAmE;IACnE,uDAAuD;IACvD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAClE,MAAM,SAAS,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;IAC5E,IAAI,SAAS,GAAG,eAAe;QAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAEvD,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC3D,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC;IACzD,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,GAAG,MAAM,CAAC,gBAAgB,GAAG,iBAAiB,EAAE,CAAC;QAC/E,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,WAAW,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE;QAC3C,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;QACd,gBAAgB,EAAE,SAAS;KAC5B,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,EAAE,IAAI;QACT,eAAe,EAAE,SAAS;QAC1B,YAAY;QACZ,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,YAAY,CAAC,GAAG,GAAG,CAAC,CAAC;QAChE,KAAK;QACL,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CACxC,GAAwB,EACxB,MAAqB;IAErB,MAAM,MAAM,GAAG;QACb,sCAAsC;QACtC,EAAE;QACF,eAAe,GAAG,CAAC,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,CAAC,YAAY,CAAC,cAAc,EAAE,YAAY,GAAG,CAAC,GAAG,cAAc,GAAG,CAAC,KAAK,6DAA6D;QACjM,EAAE;KACH,CAAC;IAEF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO;YACL,GAAG,MAAM;YACT,6HAA6H;YAC7H,EAAE;YACF,oEAAoE;YACpE,EAAE;YACF,eAAe,GAAG,GAAG,CAAC,GAAG,GAAG,OAAO,GAAG,GAAG,CAAC,KAAK,GAAG,gBAAgB;YAClE,IAAI;YACJ,kDAAkD;YAClD,wDAAwD;YACxD,EAAE;YACF,2EAA2E;SAC5E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED,OAAO;QACL,GAAG,MAAM;QACT,kBAAkB,MAAM,KAAK;QAC7B,EAAE;QACF,oEAAoE;QACpE,EAAE;QACF,eAAe,GAAG,GAAG,CAAC,GAAG,GAAG,OAAO,GAAG,GAAG,CAAC,KAAK,GAAG,gBAAgB;QAClE,IAAI;QACJ,kDAAkD;QAClD,oEAAoE;QACpE,oEAAoE;QACpE,EAAE;QACF,mGAAmG,MAAM,iJAAiJ,MAAM,mBAAmB;QACnR,EAAE;QACF,8IAA8I;KAC/I,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"context-threshold.js","sourceRoot":"","sources":["../../../src/hooks/runners/context-threshold.ts"],"names":[],"mappings":"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"}

package/dist/hooks/runners/index.d.ts

@@ -6,7 +6,6 @@
 export { runSessionStartHook } from "./session-start.js";
 export { runSessionEndHook } from "./session-end.js";
 export { runStopHook } from "./stop.js";
-export { estimateTokensFromTranscript, modelWindow, readModelFromTranscript, } from "./context-threshold.js";
 export { runUserPromptSubmitHook } from "./user-prompt-submit.js";
 export { runGcAutotriggerCheck } from "./gc-autotrigger.js";
 export type { GcAutotriggerArgv, GcAutotriggerOptions, GcAutotriggerReason, GcAutotriggerResult, } from "./gc-autotrigger.js";

package/dist/hooks/runners/index.js

@@ -6,7 +6,6 @@
 export { runSessionStartHook } from "./session-start.js";
 export { runSessionEndHook } from "./session-end.js";
 export { runStopHook } from "./stop.js";
-export { estimateTokensFromTranscript, modelWindow, readModelFromTranscript, } from "./context-threshold.js";
 export { runUserPromptSubmitHook } from "./user-prompt-submit.js";
 export { runGcAutotriggerCheck } from "./gc-autotrigger.js";
 export { renderBypassHint, scanBypassedCommits, } from "../bypass-detection.js";

package/dist/hooks/runners/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/runners/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,4BAA4B,EAC5B,WAAW,EACX,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAO5D,OAAO,EACL,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/runners/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAO5D,OAAO,EACL,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/dist/hooks/runners/phase-ready-surface.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Phase-ready surface relocation.
+ *
+ * `phase-ready-to-exit` events used to inject straight into the Stop
+ * hook's `decision: block` reason. Claude Code labels every Stop
+ * decision-block as "Stop hook error" in the operator UI — even when
+ * the block carries informational Cairn context — which the operator
+ * reads as a real failure. That visual signal is what we wanted to
+ * avoid, so the surface moved off Stop entirely:
+ *
+ *   - Stop hook collects phase-ready hints from drained events as
+ *     before, but writes them to
+ *     `.cairn/sessions/<id>/phase-ready-pending.json` instead of
+ *     emitting `decision: block`. If no other surface is pending,
+ *     Stop returns `{continue: true}` and the operator sees no
+ *     banner.
+ *   - UserPromptSubmit hook, fired on the next operator prompt,
+ *     reads the pending file, renders it as `additionalContext`,
+ *     and deletes the file. Claude Code stitches the
+ *     `additionalContext` straight into the model's next turn — no
+ *     red banner, no `decision: block`.
+ *
+ * Idempotency for the phase-ready emission itself is handled upstream
+ * in `task-link.ts` via the per-phase `ready_emitted` flag on
+ * `phase_progress`. This module is purely the Stop → UPS shuttle.
+ */
+export interface PhaseReadyHint {
+    mission_id: string;
+    mission_title: string;
+    phase_id: string;
+    phase_title: string;
+    exit_criteria: string;
+}
+/**
+ * Persist the hints the Stop hook collected so the next UPS hook can
+ * inject them as additionalContext. Overwrites any prior pending file
+ * for the session — the latest hint set wins (the operator hasn't
+ * seen the old one yet so there's nothing to merge).
+ */
+export declare function writePhaseReadyPending(repoRoot: string, sessionId: string, hints: PhaseReadyHint[]): void;
+/**
+ * Read the pending file and delete it in one shot — UPS hook semantics
+ * are "show once, then forget". When the file is missing or malformed
+ * returns null so the caller can no-op cleanly.
+ */
+export declare function readAndConsumePhaseReadyPending(repoRoot: string, sessionId: string): PhaseReadyHint[] | null;
+/**
+ * Render the operator-facing phase-ready prompt. Keeps option labels
+ * in plain English — no MCP tool-call syntax, no internal ids exposed
+ * raw — and instructs the model to surface via `AskUserQuestion`.
+ *
+ * The mission/phase ids stay in the body for traceability but the
+ * AskUserQuestion option labels themselves are human-readable phase
+ * titles, not phase ids.
+ */
+export declare function renderPhaseReadyHint(hints: PhaseReadyHint[]): string;

package/dist/hooks/runners/phase-ready-surface.js

@@ -0,0 +1,134 @@
+/**
+ * Phase-ready surface relocation.
+ *
+ * `phase-ready-to-exit` events used to inject straight into the Stop
+ * hook's `decision: block` reason. Claude Code labels every Stop
+ * decision-block as "Stop hook error" in the operator UI — even when
+ * the block carries informational Cairn context — which the operator
+ * reads as a real failure. That visual signal is what we wanted to
+ * avoid, so the surface moved off Stop entirely:
+ *
+ *   - Stop hook collects phase-ready hints from drained events as
+ *     before, but writes them to
+ *     `.cairn/sessions/<id>/phase-ready-pending.json` instead of
+ *     emitting `decision: block`. If no other surface is pending,
+ *     Stop returns `{continue: true}` and the operator sees no
+ *     banner.
+ *   - UserPromptSubmit hook, fired on the next operator prompt,
+ *     reads the pending file, renders it as `additionalContext`,
+ *     and deletes the file. Claude Code stitches the
+ *     `additionalContext` straight into the model's next turn — no
+ *     red banner, no `decision: block`.
+ *
+ * Idempotency for the phase-ready emission itself is handled upstream
+ * in `task-link.ts` via the per-phase `ready_emitted` flag on
+ * `phase_progress`. This module is purely the Stop → UPS shuttle.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function pendingPath(repoRoot, sessionId) {
+    return join(repoRoot, ".cairn", "sessions", sessionId, "phase-ready-pending.json");
+}
+/**
+ * Persist the hints the Stop hook collected so the next UPS hook can
+ * inject them as additionalContext. Overwrites any prior pending file
+ * for the session — the latest hint set wins (the operator hasn't
+ * seen the old one yet so there's nothing to merge).
+ */
+export function writePhaseReadyPending(repoRoot, sessionId, hints) {
+    if (hints.length === 0)
+        return;
+    const path = pendingPath(repoRoot, sessionId);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        const payload = {
+            ts: new Date().toISOString(),
+            session_id: sessionId,
+            hints,
+        };
+        writeFileSync(path, JSON.stringify(payload, null, 2), "utf8");
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Read the pending file and delete it in one shot — UPS hook semantics
+ * are "show once, then forget". When the file is missing or malformed
+ * returns null so the caller can no-op cleanly.
+ */
+export function readAndConsumePhaseReadyPending(repoRoot, sessionId) {
+    const path = pendingPath(repoRoot, sessionId);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    const p = parsed;
+    if (!Array.isArray(p.hints) || p.hints.length === 0) {
+        try {
+            unlinkSync(path);
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    try {
+        unlinkSync(path);
+    }
+    catch { /* ignore */ }
+    return p.hints;
+}
+/**
+ * Render the operator-facing phase-ready prompt. Keeps option labels
+ * in plain English — no MCP tool-call syntax, no internal ids exposed
+ * raw — and instructs the model to surface via `AskUserQuestion`.
+ *
+ * The mission/phase ids stay in the body for traceability but the
+ * AskUserQuestion option labels themselves are human-readable phase
+ * titles, not phase ids.
+ */
+export function renderPhaseReadyHint(hints) {
+    const h = hints[0];
+    if (h === undefined)
+        return "";
+    const lines = [];
+    lines.push(`## Cairn — phase ready to exit`);
+    lines.push("");
+    lines.push(`**Mission:** ${h.mission_title}`);
+    lines.push(`**Phase:** ${h.phase_title}`);
+    lines.push("");
+    lines.push(`Exit criteria: ${h.exit_criteria}`);
+    lines.push("");
+    lines.push("Surface this question to the operator via `AskUserQuestion`. Do NOT call `cairn_mission_advance` yourself — the operator's answer is the only valid input.");
+    lines.push("");
+    lines.push(`> Phase \`${h.phase_title}\` looks done. Move on?`);
+    lines.push(">");
+    lines.push("> - `[a]` Mark phase done, advance to next phase");
+    lines.push("> - `[b]` Keep working on this phase");
+    lines.push("");
+    lines.push(`On \`[a]\`, call \`cairn_mission_advance({phase_id: "${h.phase_id}", choice: "exit"})\`. On \`[b]\`, call \`cairn_mission_advance({phase_id: "${h.phase_id}", choice: "not_yet"})\`.`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=phase-ready-surface.js.map

package/dist/hooks/runners/phase-ready-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-ready-surface.js","sourceRoot":"","sources":["../../../src/hooks/runners/phase-ready-surface.ts"],"names":[],"mappings":"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"}