pan-wizard 3.33.0 → 3.35.0

package/commands/pan/review-deep.md

@@ -24,8 +24,6 @@ Consolidates Spec B v1's X-4 (self-review) + X-12 (harden) into a single command
 </objective>
 
 <execution_context>
-@~/.claude/pan-wizard-core/bin/lib/review-deep.cjs
-@~/.claude/pan-wizard-core/bin/lib/bus.cjs
 @~/.claude/agents/pan-hardener.md
 @~/.claude/agents/pan-meta-reviewer.md
 </execution_context>
@@ -54,7 +52,7 @@ Runs the normal exec → reviewer pipeline, then runs this command's process inl
 /pan:focus-exec --deep-review
 ```
 
-Per-item deep review during focus campaigns. Useful for high-stakes batches.
+Per-item deep review during focus campaigns: focus-exec runs the hardener and meta-reviewer on the item's changed files and merges them under the item's id (`review-deep merge <item-id>` with no `--reviewer-file`), since an item has no phase or first-pass review. Useful for high-stakes batches.
 
 </invocation_modes>
 
@@ -67,7 +65,7 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
    - Agent writes its findings to the output path, returns confirmation.
 
 3. **Spawn pan-meta-reviewer**:
-   - Prompt includes: `<files_to_read>` with both reviewer.md AND hardener.md (and representative diff snippets); `<output_path>` = `.planning/reviews/<N>/meta.md`.
+   - Prompt includes: `<files_to_read>` with both `{directory}/{phase_number}-review.md` AND `.planning/reviews/<N>/hardener.md` (and representative diff snippets); `<output_path>` = `.planning/reviews/<N>/meta.md`.
    - Agent reads both first-pass reports, identifies missed patterns, disputes overstated severities, writes to output path.
 
 4. **Merge** — call:
@@ -87,13 +85,13 @@ Per-item deep review during focus campaigns. Useful for high-stakes batches.
 
 | Verdict | Meaning | Action |
 |---------|---------|--------|
-| `ok` | No findings at any severity | Merge freely |
-| `ok_with_minor` | Only low/info findings | Merge with noted follow-ups |
+| `ok` | No findings, or info findings only | Merge freely |
+| `ok_with_minor` | Only low findings (info alone gives `ok`) | Merge with noted follow-ups |
 | `fix_before_merge` | Medium findings present | Fix or document before merge |
 | `review_required` | High findings present | Human sign-off required |
 | `block` | At least one critical | Do not merge |
 
-Verdict is driven by the highest-severity finding across all three sources. Meta-reviewer disputes can downgrade severity on specific findings but don't change the headline verdict — the merger trusts the consensus of the explicit severity labels.
+Verdict is driven by the highest-severity finding across all three sources. Meta-reviewer disputes are listed in the conflict table but change no severity, so they never lower the headline verdict; the meta-reviewer's own findings count toward it like the other two sources'.
 
 </verdict_semantics>
 
@@ -114,8 +112,8 @@ Verdict is driven by the highest-severity finding across all three sources. Meta
 | Claude Code | Full; reasoning depth from the agent's `effort:` frontmatter | Full | Full |
 | OpenCode | Prose "think step-by-step" preamble substitutes for thinking | Same | Full (runtime-agnostic CLI) |
 | Gemini | Same | Same | Full |
-| Codex | Same | Same | Full |
-| Copilot | Same | Same | Full |
+| Codex | Native — `effort:` becomes the agent TOML's `model_reasoning_effort` | Same | Full |
+| Copilot | Prose "think step-by-step" preamble, as on OpenCode | Same | Full |
 
 The merger CLI (`pan-tools review-deep merge`) is pure Node.js and works identically across runtimes. Only the *quality* of the hardener and meta-reviewer outputs varies with model capability.
 

package/commands/pan/settings.md

@@ -15,7 +15,7 @@ Interactive configuration of PAN workflow agents and model profile via multi-que
 Routes to the settings workflow which handles:
 - Config existence ensuring
 - Current settings reading and parsing
-- Interactive 5-question prompt (model, research, plan_check, verifier, branching)
+- Interactive multi-question prompt (model profile, research, plan_check, verifier, auto_advance, nyquist_validation, branching strategy, routing strategy)
 - Config merging and writing
 - Confirmation display with quick command references
 </objective>

package/commands/pan/verify-phase.md

@@ -74,17 +74,6 @@ After initial verification of each requirement:
 This prevents premature FAIL verdicts from incomplete investigation.
 </reflexion_loop>
 
-<cache_priming>
-**Before the verifier agent runs**, prime the prompt cache once. The verifier reads project.md / requirements.md / roadmap.md every run; caching avoids ~15-50K input tokens per invocation.
-
-Run once:
-```
-pan-tools cache prime --summary
-```
-
-See [plan-phase.md](plan-phase.md) or [exec-phase.md](exec-phase.md) for the full explanation. No-op on non-Claude runtimes.
-</cache_priming>
-
 <process>
 Execute the verify-phase workflow from @~/.claude/pan-wizard-core/workflows/verify-phase.md end-to-end.
 Preserve all workflow gates (the test-suite gate, the truth/artifact/wiring checks, status determination, the verification report).

package/commands/pan/what-if.md

@@ -20,7 +20,6 @@ Unchanged from Spec B v1's X-9. Already narrow enough to stand alone.
 </objective>
 
 <execution_context>
-@~/.claude/pan-wizard-core/bin/lib/whatif.cjs
 @~/.claude/agents/pan-counterfactual.md
 </execution_context>
 
@@ -56,7 +55,7 @@ If worktree creation fails (not a git repo, dirty tree blocking, etc.), abort wi
 
 ### Stage 2 — Spawn pan-counterfactual
 
-Spawn the agent with its working directory set to `worktree_path`. Prompt includes:
+Spawn the agent. A spawn cannot set its working directory — it starts in the main project — so the prompt's `<worktree_path>` is where it must work. Prompt includes:
 - `<files_to_read>` — the phase plan, any existing summary, the main project's `CLAUDE.md` so the agent understands conventions.
 - `<scenario>` — the user's scenario text verbatim.
 - `<worktree_path>` — so the agent knows the safe boundary.
@@ -69,7 +68,7 @@ The agent explores, then returns a JSON payload with `{summary, differences, rec
 Run (from main tree, NOT worktree):
 
 ```
-pan-tools whatif report <phase> "<scenario>" --comparison '<agent-json>'
+pan-tools whatif report <phase> "<scenario>" --comparison "$(cat <comparison-json-file>)"
 ```
 
 This writes `.planning/counterfactuals/<phase>-<slug>.md`. The file belongs to the main tree and survives worktree cleanup.
@@ -80,7 +79,7 @@ This writes `.planning/counterfactuals/<phase>-<slug>.md`. The file belongs to t
 pan-tools whatif cleanup --worktree <path> --branch <name> --force
 ```
 
-Removes the worktree directory and deletes the counterfactual branch. Best-effort: warnings are surfaced but don't block.
+Removes the worktree directory and deletes the counterfactual branch. Pass the `worktree.worktree_path` and `worktree.branch` that `whatif prepare` returned, unchanged. Cleanup refuses (exit 1, nothing removed) a branch outside `pan-whatif/` and a worktree that is not checked out on that branch, so it can never delete your own work. Otherwise best-effort: warnings are surfaced but don't block.
 
 ### Stage 5 — Confirm
 

package/hooks/dist/pan-context-monitor.js

@@ -1,18 +1,43 @@
 #!/usr/bin/env node
 // Context Monitor - PostToolUse hook
-// Reads context metrics from the statusline bridge file and injects
-// warnings when context usage is high. This makes the AGENT aware of
-// context limits (the statusline only shows the user).
+// Works out how full the agent's context is and injects a note when the host
+// will compact it soon. This makes the AGENT aware of context limits (the
+// statusline only shows the user).
 //
 // How it works:
 // 1. The statusline hook writes metrics to <os tmpdir>/pan-hooks-<uid>/claude-ctx-{session_id}.json
 // 2. This hook reads those metrics after each tool use
-// 3. When remaining context drops below thresholds, it injects a warning
-//    as additionalContext, which the agent sees in its conversation
+// 3. When the room left before the host compacts drops below thresholds, it
+//    injects a note as additionalContext, which the agent sees in its conversation
 //
-// Thresholds:
-//   WARNING  (remaining <= 35%): Agent should wrap up current task
-//   CRITICAL (remaining <= 25%): Agent should stop immediately and save state
+// Without the status line. `claude -p` never runs the status line (checked
+// 2026-10-04), and a user may run their own, so the bridge is often missing. Then
+// the hook reads the session transcript the payload names: the newest assistant
+// record carries the usage of the API call that issued this tool call, and its
+// input + cache-read + cache-write tokens are what the status line reports as
+// `total_input_tokens` (code.claude.com/docs/en/statusline). The model id on that
+// record gives the window. A tool call inside a subagent is measured against the
+// subagent's own transcript, never the main session's: the payload carries
+// `agent_id` and still names the MAIN transcript (Claude Code 2.1.288, captured
+// 2026-10-04). Only a bounded tail of the file is read.
+//
+// What it measures (O7). Claude Code's percentages are against the full model
+// window, but the host compacts earlier: about 33K short of the auto-compact window
+// (CLAUDE_CODE_AUTO_COMPACT_WINDOW, then `autoCompactWindow` in settings, per model
+// or for all, else the model window) — about 967K on a 1M model by default — or at
+// CLAUDE_AUTOCOMPACT_PCT_OVERRIDE's share of the window when that is lower. With
+// token counts, the room left is measured against that point; without them,
+// against the model window.
+//
+// What it says (O7). No countdown: vendor guidance is that a visible remaining-
+// context figure makes a model wrap up early and cut corners, and a note after a
+// tool result that orders it to STOP reads like an injection. The note asks for a
+// checkpoint in state.md at the next natural stopping point, says compaction is
+// safe because PAN restores the state, and asks for no shortcuts.
+//
+// Thresholds (of the room before compaction):
+//   WARNING  (left <= 35%): checkpoint at the next natural stopping point
+//   CRITICAL (left <= 25%): checkpoint before the next step
 //
 // Debounce: 5 tool uses between warnings to avoid spam
 // Severity escalation bypasses debounce (WARNING -> CRITICAL fires immediately)
@@ -92,23 +117,267 @@ function bridgeDir() {
   } catch { return null; }
 }
 
-const WARNING_THRESHOLD = 35;  // remaining_percentage <= 35%
-const CRITICAL_THRESHOLD = 25; // remaining_percentage <= 25%
+const WARNING_THRESHOLD = 35;  // room left before compaction <= 35%
+const CRITICAL_THRESHOLD = 25; // room left before compaction <= 25%
 const STALE_SECONDS = 60;      // ignore metrics older than 60s
 const DEBOUNCE_CALLS = 5;      // min tool uses between warnings
+const MIN_COMPACT_WINDOW = 100000;
+const MAX_COMPACT_WINDOW = 1000000;
+// The host compacts this far short of its window, whatever the window: about 967K on
+// a native 1M window (code.claude.com/docs/en/model-config), and on 2026-10-04 a 100K
+// autoCompactWindow compacted after a call that measured 67,032 tokens and not after
+// one that measured 54,371 (harness context-note-headless). A margin proportional to
+// the window would have put that compaction at ~96.7K.
+const COMPACT_MARGIN = 33000;
+const STANDARD_WINDOW = 200000;
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;      // the first read from the end of the transcript
+const TRANSCRIPT_MAX_BYTES = 4 * 1024 * 1024;  // never read more than this of it
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/; // session and agent ids name files
+
+/**
+ * The token count at which the host compacts this session, or null when it does
+ * not compact: the compaction window less COMPACT_MARGIN, or the percentage
+ * override's share of the window when that is lower. Pure over its inputs.
+ *   modelWindow — context_window_size from the statusline
+ *   modelId     — the model id, for `modelSettings.<id>.autoCompactWindow`
+ *   env         — the environment (CLAUDE_CODE_AUTO_COMPACT_WINDOW,
+ *                 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, DISABLE_AUTO_COMPACT)
+ *   settings    — settings objects, highest precedence first (local, project, user)
+ */
+function compactTrigger({ modelWindow, modelId, env = {}, settings = [] }) {
+  if (!Number.isFinite(modelWindow) || modelWindow <= 0) return null;
+  if (env.DISABLE_AUTO_COMPACT === '1') return null;
+  for (const s of settings) if (s && s.autoCompactEnabled === false) return null;
+  const clamp = (n) => Math.min(modelWindow, Math.max(MIN_COMPACT_WINDOW, Math.min(MAX_COMPACT_WINDOW, n)));
+  let window = null;
+  if (/^\d+$/.test(String(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || ''))) {
+    window = clamp(Number(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW));
+  } else {
+    for (const s of settings) {
+      if (!s || typeof s !== 'object') continue;
+      const perModel = modelId && s.modelSettings && s.modelSettings[modelId] ? s.modelSettings[modelId].autoCompactWindow : undefined;
+      const v = perModel !== undefined ? perModel : s.autoCompactWindow;
+      if (v === 'auto') break; // the tuned default, below
+      if (Number.isFinite(v)) { window = clamp(v); break; }
+    }
+  }
+  if (window == null) window = Math.min(modelWindow, MAX_COMPACT_WINDOW);
+  let trigger = window - COMPACT_MARGIN;
+  const pct = Number(env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE);
+  if (Number.isInteger(pct) && pct >= 1 && pct < 100) trigger = Math.min(trigger, Math.floor(window * pct / 100));
+  return trigger;
+}
+
+/**
+ * The room left before compaction, as a percentage, and what it was measured
+ * against. Falls back to the model window's remaining_percentage when the bridge
+ * carries no token counts or the host does not compact.
+ */
+function roomLeft(metrics, opts = {}) {
+  const used = Number(metrics.total_input_tokens);
+  const trigger = Number.isFinite(used)
+    ? compactTrigger({ modelWindow: Number(metrics.context_window_size), modelId: metrics.model_id, env: opts.env || {}, settings: opts.settings || [] })
+    : null;
+  if (trigger) return { remaining: Math.max(0, Math.min(100, ((trigger - used) / trigger) * 100)), basis: 'compact-window' };
+  const r = Number(metrics.remaining_percentage);
+  return { remaining: r, basis: 'model-window' };
+}
+
+// ─── Without the status line: the transcript ─────────────────────────────────
+
+/**
+ * Pure: the context of the newest API call in a transcript's lines, scanning back
+ * from the end. Returns `{ found: true, used, model }`, `{ found: false, compacted:
+ * true }` when a compaction boundary comes first (the context was just rebuilt and
+ * no call has measured it yet), or `{ found: false }` when these lines hold no
+ * assistant record, so the caller can read further back.
+ *
+ * `used` is input + cache-read + cache-write tokens, the status line's
+ * `total_input_tokens`. Output tokens are left out, as its `used_percentage` leaves
+ * them out. A record with no usage (a synthetic or error record) is skipped. In the
+ * main transcript a sidechain record (an older host's subagent turn) is skipped; in
+ * a subagent's own transcript every record is a sidechain one.
+ */
+function lastContextFromLines(lines, { skipSidechain = true } = {}) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line || (!line.includes('"assistant"') && !line.includes('"compact_boundary"'))) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { continue; }
+    if (!e || typeof e !== 'object') continue;
+    if (e.type === 'system' && e.subtype === 'compact_boundary') return { found: false, compacted: true };
+    if (e.type !== 'assistant' || (skipSidechain && e.isSidechain === true)) continue;
+    const u = e.message && e.message.usage;
+    if (!u || typeof u !== 'object') continue;
+    const n = (v) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0);
+    const used = n(u.input_tokens) + n(u.cache_read_input_tokens) + n(u.cache_creation_input_tokens);
+    if (used <= 0) continue;
+    return { found: true, used, model: typeof e.message.model === 'string' ? e.message.model : null };
+  }
+  return { found: false };
+}
+
+/**
+ * The last `bytes` of a file as text, without the partial line the cut starts in.
+ * Defensive only: in well-formed JSONL a line's tail never parses as an object (a
+ * nested object is always followed by its parent's closing brace), so keeping the
+ * fragment would change nothing; dropping it keeps a fragment from ever being read.
+ */
+function readTail(file, bytes) {
+  // Read-only; the owner-only mode never applies to an open for reading, but keeps the
+  // call in the form PAN's temp-dir rule requires (the path may be under the temp dir).
+  const fd = fs.openSync(file, 'r', 0o600);
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - bytes);
+    const buf = Buffer.alloc(size - start);
+    fs.readSync(fd, buf, 0, buf.length, start);
+    let text = buf.toString('utf8');
+    if (start > 0) {
+      const nl = text.indexOf('\n');
+      text = nl === -1 ? '' : text.slice(nl + 1);
+    }
+    return { text, whole: start === 0 };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * The context of the newest API call in a transcript file, or null. Reads the
+ * tail, and further back (up to TRANSCRIPT_MAX_BYTES) only while a large tool
+ * result hides the last assistant record. Fails open: any error is null.
+ */
+function contextFromTranscript(file, { skipSidechain = true, tailBytes = TRANSCRIPT_TAIL_BYTES, maxBytes = TRANSCRIPT_MAX_BYTES } = {}) {
+  if (typeof file !== 'string' || !file) return null;
+  let bytes = tailBytes;
+  for (;;) {
+    let tail;
+    try { tail = readTail(file, bytes); } catch { return null; }
+    const r = lastContextFromLines(tail.text.split('\n'), { skipSidechain });
+    if (r.found) return { used: r.used, model: r.model };
+    if (r.compacted || tail.whole || bytes >= maxBytes) return null;
+    bytes = Math.min(bytes * 4, maxBytes);
+  }
+}
+
+/**
+ * Pure: a Claude model id's family and version, or null. Accepts the API ids
+ * (`claude-opus-5-5`, `claude-haiku-4-5-20251001`, `claude-3-5-sonnet-20241022`)
+ * and marks the forms a third-party provider gives them (`us.anthropic.claude-…-v1:0`
+ * on Bedrock, `claude-…@date` on Google Cloud).
+ */
+function parseModelId(id) {
+  if (typeof id !== 'string' || !id) return null;
+  const s = id.toLowerCase().trim().replace(/\[1m\]$/, '');
+  const thirdParty = /(^|\.)anthropic\.|@|-v\d+(:\d+)?$|^arn:/.test(s);
+  let m = s.match(/claude-(opus|sonnet|haiku|fable)-(\d+)(?:-(\d{1,2}))?(?!\d)/);
+  if (m) return { family: m[1], major: Number(m[2]), minor: m[3] === undefined ? 0 : Number(m[3]), thirdParty };
+  m = s.match(/claude-(\d+)(?:-(\d{1,2}))?-(opus|sonnet|haiku)/);
+  if (m) return { family: m[3], major: Number(m[1]), minor: m[2] === undefined ? 0 : Number(m[2]), thirdParty };
+  return null;
+}
+
+/**
+ * Pure: the context window of the model that wrote a transcript record, or null
+ * when it cannot be known — then the hook says nothing rather than guess. From
+ * code.claude.com/docs/en/model-config (read 2026-10-04):
+ *   - On the Anthropic API, Fable 5.x, Sonnet 5 and later and Opus 4.7 and later
+ *     run a native 1M window. On Bedrock, Google Cloud and Foundry some of them run
+ *     200K, so there the window is unknown.
+ *   - Opus 4.6 and Sonnet 4.6 (and older) run 200K unless their `[1m]` variant is
+ *     configured; Haiku runs 200K.
+ *   - CLAUDE_CODE_DISABLE_1M_CONTEXT=1 holds every model to 200K.
+ *   - A context already past 200K can only be in a 1M window.
+ */
+function modelWindowFor(modelId, { env = {}, settings = [], used = 0 } = {}) {
+  if (used > STANDARD_WINDOW) return MAX_COMPACT_WINDOW;
+  if (env.CLAUDE_CODE_DISABLE_1M_CONTEXT === '1') return STANDARD_WINDOW;
+  const m = parseModelId(modelId);
+  if (!m) return null;
+  const native1m = m.family === 'fable'
+    || (m.family === 'sonnet' && m.major >= 5)
+    || (m.family === 'opus' && (m.major > 4 || (m.major === 4 && m.minor >= 7)));
+  if (native1m) {
+    const thirdParty = m.thirdParty || ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY']
+      .some((k) => env[k] === '1' || env[k] === 'true');
+    return thirdParty ? null : MAX_COMPACT_WINDOW;
+  }
+  if (m.family === 'haiku') return STANDARD_WINDOW;
+  const extended = [env.ANTHROPIC_MODEL, ...settings.map((s) => (s && typeof s === 'object' ? s.model : undefined))]
+    .some((v) => typeof v === 'string' && /\[1m\]\s*$/i.test(v));
+  return extended ? MAX_COMPACT_WINDOW : STANDARD_WINDOW;
+}
+
+/**
+ * Metrics shaped like the bridge's, from a transcript: the tokens in context, the
+ * model window and the model id. Null when the transcript, its usage or the window
+ * cannot be known.
+ */
+function metricsFromTranscript(file, { env = {}, settings = [], skipSidechain = true, tailBytes, maxBytes } = {}) {
+  const ctx = contextFromTranscript(file, { skipSidechain, tailBytes, maxBytes });
+  if (!ctx) return null;
+  const window = modelWindowFor(ctx.model, { env, settings, used: ctx.used });
+  if (!window) return null;
+  return {
+    total_input_tokens: ctx.used,
+    context_window_size: window,
+    ...(ctx.model ? { model_id: ctx.model } : {}),
+    remaining_percentage: Math.max(0, 100 - (ctx.used / window) * 100),
+    source: 'transcript',
+  };
+}
+
+/**
+ * Which transcript measures this tool call. A call inside a subagent carries
+ * `agent_id`; the payload's `transcript_path` is still the main session's, and the
+ * subagent's own file is `<dir>/<session>/subagents/agent-<id>.jsonl` (an
+ * `agent_transcript_path`, where a host sends one, wins). A subagent the Workflow
+ * tool spawned (PAN's native `/pan-*` workflow scripts) is written one level down,
+ * under the run that spawned it: `subagents/workflows/<run>/agent-<id>.jsonl`, found
+ * the way pan-cost-logger.js resolveAgentTranscript finds it. The directory is read
+ * only for that search. Null when the ids are not safe to put in a path.
+ */
+function transcriptForPayload(data) {
+  if (!data || typeof data !== 'object') return null;
+  const agentId = data.agent_id;
+  if (agentId === undefined || agentId === null || agentId === '') {
+    return typeof data.transcript_path === 'string' && data.transcript_path ? { file: data.transcript_path, subagent: false } : null;
+  }
+  if (typeof agentId !== 'string' || !SAFE_ID.test(agentId)) return null;
+  if (typeof data.agent_transcript_path === 'string' && data.agent_transcript_path) return { file: data.agent_transcript_path, subagent: true };
+  if (typeof data.transcript_path !== 'string' || !data.transcript_path) return null;
+  if (typeof data.session_id !== 'string' || !SAFE_ID.test(data.session_id)) return null;
+  const base = path.dirname(data.transcript_path);
+  const subagentsDir = path.join(base, data.session_id, 'subagents');
+  const direct = path.join(subagentsDir, `agent-${agentId}.jsonl`);
+  if (!fs.existsSync(direct)) {
+    const resolvedBase = path.resolve(base);
+    let runs = [];
+    try { runs = fs.readdirSync(path.join(subagentsDir, 'workflows')); } catch { /* no workflow runs */ }
+    for (const run of runs) {
+      const nested = path.join(subagentsDir, 'workflows', run, `agent-${agentId}.jsonl`);
+      if (path.resolve(nested).startsWith(resolvedBase + path.sep) && fs.existsSync(nested)) return { file: nested, subagent: true };
+    }
+  }
+  return { file: direct, subagent: true };
+}
 
 // Pure decision function (exported for tests).
 //
-//   metrics    — { remaining_percentage, used_pct?, timestamp? } from the bridge
+//   metrics    — { remaining_percentage, total_input_tokens?, context_window_size?,
+//                  model_id?, timestamp? } from the bridge, or the same shape from
+//                  metricsFromTranscript (no timestamp: measured now)
 //   warnState  — { callsSinceWarn, lastLevel } from the prior warn file, or null
 //                on the first warning (no file yet / corrupt file)
 //   nowSeconds — current unix time in seconds
+//   opts       — { env, settings } for the compaction point (see compactTrigger)
 //
 // Returns one of:
 //   { action: 'exit' }                                   — nothing to do
 //   { action: 'debounce', warnState }                    — persist counter, no warn
-//   { action: 'emit', level, warnState, message }        — persist + emit warning
-function buildContextWarning(metrics, warnState, nowSeconds) {
+//   { action: 'emit', level, warnState, message, basis } — persist + emit the note
+function buildContextWarning(metrics, warnState, nowSeconds, opts = {}) {
   if (!metrics || typeof metrics !== 'object') return { action: 'exit' };
 
   // Ignore stale metrics (statusline stopped updating — e.g. session ended).
@@ -116,7 +385,7 @@ function buildContextWarning(metrics, warnState, nowSeconds) {
     return { action: 'exit' };
   }
 
-  const remaining = Number(metrics.remaining_percentage);
+  const { remaining, basis } = roomLeft(metrics, opts);
   if (!Number.isFinite(remaining)) return { action: 'exit' };
 
   // No warning needed
@@ -140,33 +409,50 @@ function buildContextWarning(metrics, warnState, nowSeconds) {
     };
   }
 
-  // L39: report Usage and Remaining on the SAME scale so they are internally
-  // consistent (sum to 100). The bridge's used_pct is the statusline's
-  // 80%-rescaled figure (80% real usage displays as 100%); pairing it with the
-  // raw remaining produced self-contradictory numbers like
-  // "Usage at 94%. Remaining: 25%". Derive used from remaining instead.
-  const rem = Math.round(remaining);
-  const used = 100 - rem;
-
-  let message;
-  if (isCritical) {
-    message = `CONTEXT MONITOR CRITICAL: Usage at ${used}%. Remaining: ${rem}%. ` +
-      'STOP new work immediately. Save state NOW and inform the user that context is nearly exhausted. ' +
-      'If using PAN, run /pan:pause to save execution state.';
-  } else {
-    message = `CONTEXT MONITOR WARNING: Usage at ${used}%. Remaining: ${rem}%. ` +
-      'Begin wrapping up current task. Do not start new complex work. ' +
-      'If using PAN, consider /pan:pause to save state.';
-  }
+  // No figures (O7): a countdown makes a model wrap up early, and a percentage is
+  // the thing it would count down. The note names the checkpoint, says compaction
+  // is safe, and asks for no shortcuts.
+  const message = isCritical
+    ? 'PAN context note (from the context-monitor hook, not the user): the host will compact this session soon. ' +
+      'Before your next step, make sure .planning/state.md records where you are — the phase, the plan and task, and what comes next; /pan:pause writes it. ' +
+      'Then carry on with the current task as normal. After compaction PAN restores the planning state, so finish the task properly rather than quickly.'
+    : 'PAN context note (from the context-monitor hook, not the user): this session\'s context is filling up. ' +
+      'At your next natural stopping point, such as a finished task or a commit, make sure .planning/state.md records where you are; /pan:pause writes it. ' +
+      'Nothing needs to stop: the host compacts on its own and PAN restores the planning state afterwards, so keep working at full quality, with no shortcuts and no skipped verification.';
 
   return {
     action: 'emit',
     level: currentLevel,
     warnState: { callsSinceWarn: 0, lastLevel: currentLevel },
     message,
+    basis,
   };
 }
 
+/**
+ * Claude Code's settings for a project, highest precedence first: local, project, user.
+ * The user file lives in CLAUDE_CONFIG_DIR when that is set, as Claude Code reads it.
+ * A given homeDir is a test seam and ignores CLAUDE_CONFIG_DIR (as the statusline and
+ * hygiene do), unless configDir is passed too.
+ */
+function readClaudeSettings(projectDir, homeArg, configArg) {
+  const seam = homeArg !== undefined;
+  const homeDir = seam ? homeArg : os.homedir();
+  const configDir = configArg !== undefined ? configArg : (seam ? '' : (process.env.CLAUDE_CONFIG_DIR || ''));
+  // Assembled, not a literal: the installer rewrites quoted .claude literals in hook
+  // copies, and these are Claude Code's own settings (only it writes the bridge).
+  const dir = ['.', 'claude'].join('');
+  const files = [];
+  if (typeof projectDir === 'string' && projectDir) files.push(path.join(projectDir, dir, 'settings.local.json'), path.join(projectDir, dir, 'settings.json'));
+  if (configDir) files.push(path.join(configDir, 'settings.json'));
+  else if (homeDir) files.push(path.join(homeDir, dir, 'settings.json'));
+  const out = [];
+  for (const f of files) {
+    try { out.push(JSON.parse(fs.readFileSync(f, 'utf8'))); } catch { /* absent or unreadable */ }
+  }
+  return out;
+}
+
 function main() {
   let input = '';
   process.stdin.setEncoding('utf8');
@@ -177,27 +463,37 @@ function main() {
       if (deferToClaudeRegistration(data.cwd || process.cwd())) process.exit(0);
       const sessionId = data.session_id;
 
-      if (!sessionId) {
+      if (typeof sessionId !== 'string' || !SAFE_ID.test(sessionId)) {
         process.exit(0);
       }
 
       const tmpDir = bridgeDir();
       if (!tmpDir) process.exit(0); // insecure/unavailable bridge dir — fail closed (M60)
-      const metricsPath = path.join(tmpDir, `claude-ctx-${sessionId}.json`);
+      const now = Math.floor(Date.now() / 1000);
+      const settings = readClaudeSettings(data.cwd || process.cwd());
+      const source = transcriptForPayload(data);
+      const subagent = !!(source && source.subagent) || (data.agent_id !== undefined && data.agent_id !== null && data.agent_id !== '');
 
-      // Read metrics directly; absence (subagent/fresh session) or a corrupt
-      // file just means "nothing to warn about" — exit silently. No
+      // The bridge is the main session's context (the status line renders the main
+      // thread), so only a main-thread call reads it, and only while it is fresh.
+      // Absence or a corrupt file falls through to the transcript. No
       // existsSync-then-read gap.
-      let metrics;
-      try {
-        metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
-      } catch {
-        process.exit(0);
+      let metrics = null;
+      if (!subagent) {
+        try {
+          const bridge = JSON.parse(fs.readFileSync(path.join(tmpDir, `claude-ctx-${sessionId}.json`), 'utf8'));
+          if (bridge && typeof bridge === 'object' && !(bridge.timestamp != null && (now - bridge.timestamp) > STALE_SECONDS)) metrics = bridge;
+        } catch { /* no bridge: no status line, or not PAN's */ }
       }
-      const now = Math.floor(Date.now() / 1000);
+      if (!metrics && source) {
+        metrics = metricsFromTranscript(source.file, { env: process.env, settings, skipSidechain: !source.subagent });
+      }
+      if (!metrics) process.exit(0);
 
       // Load prior warn state (null when no file / corrupt → treated as first warn).
-      const warnPath = path.join(tmpDir, `claude-ctx-${sessionId}-warned.json`);
+      // A subagent debounces on its own: its context is not the main session's.
+      const warnKey = source && source.subagent ? `${sessionId}-${data.agent_id}` : sessionId;
+      const warnPath = path.join(tmpDir, `claude-ctx-${warnKey}-warned.json`);
       let warnData = null;
       try {
         warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
@@ -205,7 +501,10 @@ function main() {
         warnData = null;
       }
 
-      const decision = buildContextWarning(metrics, warnData, now);
+      const decision = buildContextWarning(metrics, warnData, now, {
+        env: process.env,
+        settings: Number.isFinite(Number(metrics.total_input_tokens)) ? settings : [],
+      });
 
       if (decision.action === 'exit') {
         process.exit(0);
@@ -241,7 +540,16 @@ if (require.main === module) {
 module.exports = {
   deferToClaudeRegistration,
   buildContextWarning,
+  compactTrigger,
+  roomLeft,
+  readClaudeSettings,
   bridgeDir,
+  lastContextFromLines,
+  contextFromTranscript,
+  parseModelId,
+  modelWindowFor,
+  metricsFromTranscript,
+  transcriptForPayload,
   WARNING_THRESHOLD,
   CRITICAL_THRESHOLD,
   STALE_SECONDS,