pan-wizard 3.29.0 → 3.31.0

package/commands/pan/audit-deployment.md

@@ -77,7 +77,7 @@ For the detected runtime config directory (CONFIG_DIR), audit ALL of the followi
 - [ ] `CONFIG_DIR/pan-wizard-core/references/` — non-empty, every manifest-listed reference present
 
 **1.4 Commands**
-- For Claude/Gemini: `CONFIG_DIR/commands/pan/` — every manifest-listed command file present
+- For Claude/Gemini: `CONFIG_DIR/commands/pan/` — every manifest-listed command file present (a `--unified-skills` install has none: check `./.agents/skills/pan-*/SKILL.md`, and for Claude also `CONFIG_DIR/skills/pan-*/SKILL.md`)
 - For OpenCode: `CONFIG_DIR/commands/` — every manifest-listed `pan-*.md` present (flat, one file per command)
 - For Copilot: `CONFIG_DIR/skills/pan-*/SKILL.md` — every manifest-listed skill directory present
 - For Codex: the SHARED skills tree, not `CONFIG_DIR` — `./.agents/skills/pan-*/SKILL.md` for a local
@@ -95,7 +95,7 @@ For the detected runtime config directory (CONFIG_DIR), audit ALL of the followi
 
 **1.7 Settings/Config**
 - [ ] Settings file exists (settings.json / opencode.json / config.json)
-- [ ] Hooks are registered in settings (SessionStart, PostToolUse, statusLine)
+- [ ] Hooks are registered — Claude `settings.json`: SessionStart, PostToolUse, SubagentStop, Stop, statusLine; Gemini `settings.json`: SessionStart and AfterAgent only (no statusLine); Codex: `.codex/hooks.json`; Copilot: `.github/hooks/pan.json`
 - [ ] Hook commands point to existing files
 
 **1.8 Manifest Integrity**

package/commands/pan/cost.md

@@ -123,7 +123,7 @@ When a record has neither a known model nor a known tier, its cost is `null` and
 
 <instrumentation_note>
 
-Token records are written by any caller that knows its usage — typically the host runtime or a wrapper. PAN ships the log format + aggregator (this command); the capture hook itself is opt-in (Wave 5 of Spec B v2). Until then, records can be appended manually via `pan-tools cost append` or by external scripts reading the provider API.
+Token records are written by any caller that knows its usage — typically the host runtime or a wrapper. PAN ships the log format, this aggregator, and the `pan-cost-logger` capture hook, which the installer registers on Claude Code, Codex and Copilot CLI. Elsewhere, records can be appended manually via `pan-tools cost append` or by external scripts reading the provider API.
 
 If `.planning/metrics/tokens.jsonl` is empty, `/pan:cost` returns zero totals — the feature is inert, not broken.
 
@@ -134,10 +134,10 @@ If `.planning/metrics/tokens.jsonl` is empty, `/pan:cost` returns zero totals
 | Runtime | Support |
 |---------|---------|
 | Claude Code | Full — data format + aggregation + all output formats |
-| OpenCode | Full aggregator; token capture depends on OpenCode's own hooks |
-| Gemini | Full aggregator; token capture depends on Gemini CLI instrumentation |
-| Codex | Full aggregator; token capture via external script |
-| Copilot CLI | Full aggregator; Copilot doesn't currently expose per-call usage |
+| OpenCode | Full aggregator; PAN registers no hooks on OpenCode, so records come from `pan-tools cost append` or an external script |
+| Gemini | Full aggregator; PAN registers no cost hook on Gemini CLI (no subagent-completion event), so records come from `pan-tools cost append` or an external script |
+| Codex | Full — `pan-cost-logger` registered on `SubagentStop` in `.codex/hooks.json` |
+| Copilot CLI | Full aggregator; `pan-cost-logger` registered on `subagentStop` in `.github/hooks/pan.json` (token counts depend on what the payload carries) |
 
 The aggregator is runtime-agnostic. What varies across runtimes is how records *get into* `tokens.jsonl` in the first place.
 

package/commands/pan/exec-phase.md

@@ -117,6 +117,8 @@ Next: Wave {N+1} — {task count} tasks [{task IDs}]
 ```
 This prevents drift in multi-wave phases where the agent loses track of which waves remain and what the test baseline was.
 
+**Task tracking:** where your runtime offers a todo or task-tracking tool, you may keep the wave list in it. Do not depend on one: some runtimes offer none on their newest models (Claude Code gates its task tools behind `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` there). The attention anchor above, the wave summaries and state.md are the record either way.
+
 **State Intent Before Implementing (M+ tasks):**
 For each STANDARD or FULL task, state before coding: "I will modify [files], adding [what], to achieve [goal]. Risk: [what could break]."
 

package/commands/pan/focus-auto.md

@@ -1,7 +1,7 @@
 ---
 name: focus-auto
 group: Focus
-description: Continuous scan-plan-exec loop with purpose-driven categories and 5-layer safety harness
+description: Continuous scan-plan-exec loop with purpose-driven categories and a layered safety harness
 allowed-tools:
   - Read
   - Write
@@ -107,7 +107,7 @@ Wait for the user's reply before proceeding. Do not guess or pick a default cate
 | `--stop` | — | Gracefully stop active run |
 | `--status` | — | Show current campaign progress |
 | `--dry-run` | — | Show plan without executing |
-| `--deep-review` | off | After every exec cycle, run inline OWASP security check on changed files. Verdict `block` or `review_required` stops the campaign (6th safety harness). Works with all categories. |
+| `--deep-review` | off | After every exec cycle, run inline OWASP security check on changed files. Verdict `block` or `review_required` stops the campaign (the security-gate layer of the safety harness). Works with all categories. |
 | `--parallel-research` | off | Fan out the per-item *research* stage via the Workflow tool (read-only agents). No-op fallback to sequential where the host has no Workflow tool. (ADR-0031) |
 | `--parallel-verify` | off | Fan out the per-item *verify* stage via the Workflow tool (read-only). The implement/exec stage always stays a single agent. (ADR-0031) |
 | `--clean-seal` | off | After the loop's last item, run one clean build + full verification (commands from `config.json → build`/`verification`) to catch cross-item orphans. (ADR-0031) |
@@ -185,7 +185,7 @@ Phase 2 (each cycle): Scan → Plan → Exec → Commit is strictly sequential w
 HARD STOP conditions:
 - Phase 1 fails (tests broken): Do not enter main loop — report and exit
 - Any cycle: test count drops below baseline after revert → stop campaign, preserve state
-- Context drops below 25%: stop campaign cleanly (safety harness 3)
+- Context drops below 25%: stop campaign cleanly (safety harness)
 </phase_dependencies>
 
 ### Phase 2: Main Loop
@@ -413,7 +413,7 @@ Then continue immediately to the next cycle (back to Step 2.1).
 
 4. Remove safety tag: `git tag -d focus-auto-baseline 2>/dev/null`
 
-## 6-Layer Safety Harness
+## Layered Safety Harness
 
 | Layer | Mechanism | Action |
 |-------|-----------|--------|
@@ -425,7 +425,7 @@ Then continue immediately to the next cycle (back to Step 2.1).
 | Zero-completed guard | 0 items done in a cycle | Stop — further cycles won't help |
 | Security gate (`--deep-review`) | Critical/high OWASP pattern in changed files | Revert last commit (critical) or flag for manual review (high), stop campaign |
 
-## 9 Behavioral Rules
+## Behavioral Rules
 
 1. **Read Before Write** — Read every file before editing. Understand context, callers, invariants.
 2. **Root Cause** — Fix the actual defect, not symptoms. Trace the code path.

package/commands/pan/verify-phase.md

@@ -1,7 +1,7 @@
 ---
 name: pan:verify-phase
 group: Phase Lifecycle
-description: Validate built features through conversational UAT with test suite gate
+description: Re-run goal-backward verification of a phase with a test-suite gate and list its gaps
 argument-hint: "[phase number, e.g., '4']"
 allowed-tools:
   - Read
@@ -13,24 +13,23 @@ allowed-tools:
   - Task
 ---
 <objective>
-Validate built features through conversational testing with persistent state.
+Verify that the phase delivered what it promised, not just that its tasks completed.
 
-Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution.
+Purpose: goal-backward verification — what must be TRUE for the phase goal, what must EXIST for that, what must be WIRED — checked against the codebase, behind a test-suite gate.
 
-Output: {phase_num}-uat.md tracking all test results. If issues found: diagnosed gaps, verified fix plans ready for /pan:exec-phase
+Output: {phase_num}-verification.md with a status (passed, gaps_found or human_needed). Gaps found are listed for `/pan:plan-phase {phase_num} --gaps`.
 </objective>
 
 <execution_context>
 @~/.claude/pan-wizard-core/workflows/verify-phase.md
-@~/.claude/pan-wizard-core/templates/uat.md
 </execution_context>
 
 <context>
 Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")
-- If not provided: Check for active sessions or prompt for phase
+- If not provided: prompt for the phase
 
-Context files are resolved inside the workflow (`init verify-work`) and delegated via `<files_to_read>` blocks.
+Context files are resolved inside the workflow (`init phase-op`).
 </context>
 
 <investigate_before_judging>
@@ -87,6 +86,6 @@ See [plan-phase.md](plan-phase.md) or [exec-phase.md](exec-phase.md) for the ful
 </cache_priming>
 
 <process>
-Execute the verify-work workflow from @~/.claude/pan-wizard-core/workflows/verify-phase.md end-to-end.
-Preserve all workflow gates (session management, test presentation, diagnosis, fix planning, routing).
+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).
 </process>

package/hooks/dist/pan-check-update.js

@@ -12,6 +12,45 @@
 
 const fs = require('fs');
 const path = require('path');
+
+// ─── R39: one run per hook when Claude and Copilot share a project ───────────
+// Copilot CLI also runs the hooks in a repository's .claude/settings.json and
+// .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
+// hooks loaded): in a project with both the Claude and the Copilot install, every
+// PAN hook ran twice under Copilot — once from .github/hooks/pan.json, once from the
+// Claude settings. The Copilot project copy (this file under .github/hooks) steps
+// aside whenever the project's Claude settings register the same script, so the hook
+// runs once, and runs again from here the moment the Claude registration is gone.
+// Both files are repository hooks to Copilot and load under the same trust rule, so
+// deferring never leaves zero. Only this copy defers: Claude Code never reads
+// .github/hooks, Gemini and Codex never read .claude/settings.json, and a global
+// Copilot copy loads where repository hooks may not. Identical in every hook
+// Copilot registers — tests/copilot-hook-dedupe.test.cjs pins the copies.
+function deferToClaudeRegistration(projectDir, hookFile = __filename) {
+  // Assembled, not written as a literal: the installer rewrites every quoted .claude
+  // literal in a hook copy to that runtime's own directory, and this one must stay Claude's.
+  const claudeDir = ['.', 'claude'].join('');
+  try {
+    const hooksDir = path.dirname(hookFile);
+    if (path.basename(hooksDir) !== 'hooks' || path.basename(path.dirname(hooksDir)) !== '.github') return false;
+    if (typeof projectDir !== 'string' || !projectDir) return false;
+    const script = path.basename(hookFile);
+    for (const name of ['settings.json', 'settings.local.json']) {
+      let settings;
+      try { settings = JSON.parse(fs.readFileSync(path.join(projectDir, claudeDir, name), 'utf8')); } catch { continue; }
+      const events = settings && typeof settings.hooks === 'object' ? settings.hooks : null;
+      if (!events) continue;
+      for (const groups of Object.values(events)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          const handlers = group && Array.isArray(group.hooks) ? group.hooks : [];
+          if (handlers.some((h) => h && typeof h.command === 'string' && h.command.includes(script))) return true;
+        }
+      }
+    }
+  } catch { /* fail open: run this copy */ }
+  return false;
+}
 const os = require('os');
 const { spawn } = require('child_process');
 
@@ -128,9 +167,17 @@ function main() {
   const cacheDir = path.join(homeDir, '.claude', 'cache');
   const cacheFile = path.join(cacheDir, 'pan-update-check.json');
 
-  // VERSION file locations (check project first, then global)
+  // VERSION file locations: the project's own install first; then the core this
+  // hook copy ships with, which sits beside it in every layout (<config>/hooks next
+  // to <config>/pan-wizard-core, and the same under a plugin root); then the global
+  // install. The plugin case is why the middle one exists: the two config-dir paths
+  // only ever find an install, so under a plugin host the installed version read as
+  // 0.0.0 (3.28.0 review, LOW).
   const projectVersionFile = path.join(cwd, '.claude', 'pan-wizard-core', 'VERSION');
-  const globalVersionFile = path.join(homeDir, '.claude', 'pan-wizard-core', 'VERSION');
+  const ownVersionFile = path.join(__dirname, '..', 'pan-wizard-core', 'VERSION');
+  const globalVersionFile = fs.existsSync(ownVersionFile)
+    ? ownVersionFile
+    : path.join(homeDir, '.claude', 'pan-wizard-core', 'VERSION');
 
   // Ensure cache directory exists
   try {
@@ -153,6 +200,9 @@ function main() {
     return;
   }
 
+  // Copilot also runs the Claude registration of this hook in a two-runtime project.
+  if (deferToClaudeRegistration(cwd)) return;
+
   // Parent mode: run the check in a detached background child so the 10s
   // `npm view` never blocks SessionStart. windowsHide prevents a console flash.
   const child = spawn(process.execPath, [__filename, '--run-check'], {
@@ -168,6 +218,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  deferToClaudeRegistration,
   parseVersion,
   compareVersions,
   isUpdateAvailable,

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

@@ -25,6 +25,45 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+// ─── R39: one run per hook when Claude and Copilot share a project ───────────
+// Copilot CLI also runs the hooks in a repository's .claude/settings.json and
+// .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
+// hooks loaded): in a project with both the Claude and the Copilot install, every
+// PAN hook ran twice under Copilot — once from .github/hooks/pan.json, once from the
+// Claude settings. The Copilot project copy (this file under .github/hooks) steps
+// aside whenever the project's Claude settings register the same script, so the hook
+// runs once, and runs again from here the moment the Claude registration is gone.
+// Both files are repository hooks to Copilot and load under the same trust rule, so
+// deferring never leaves zero. Only this copy defers: Claude Code never reads
+// .github/hooks, Gemini and Codex never read .claude/settings.json, and a global
+// Copilot copy loads where repository hooks may not. Identical in every hook
+// Copilot registers — tests/copilot-hook-dedupe.test.cjs pins the copies.
+function deferToClaudeRegistration(projectDir, hookFile = __filename) {
+  // Assembled, not written as a literal: the installer rewrites every quoted .claude
+  // literal in a hook copy to that runtime's own directory, and this one must stay Claude's.
+  const claudeDir = ['.', 'claude'].join('');
+  try {
+    const hooksDir = path.dirname(hookFile);
+    if (path.basename(hooksDir) !== 'hooks' || path.basename(path.dirname(hooksDir)) !== '.github') return false;
+    if (typeof projectDir !== 'string' || !projectDir) return false;
+    const script = path.basename(hookFile);
+    for (const name of ['settings.json', 'settings.local.json']) {
+      let settings;
+      try { settings = JSON.parse(fs.readFileSync(path.join(projectDir, claudeDir, name), 'utf8')); } catch { continue; }
+      const events = settings && typeof settings.hooks === 'object' ? settings.hooks : null;
+      if (!events) continue;
+      for (const groups of Object.values(events)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          const handlers = group && Array.isArray(group.hooks) ? group.hooks : [];
+          if (handlers.some((h) => h && typeof h.command === 'string' && h.command.includes(script))) return true;
+        }
+      }
+    }
+  } catch { /* fail open: run this copy */ }
+  return false;
+}
+
 // Per-user bridge directory inside tmpdir, created 0700 so another user on a
 // shared host can't pre-plant a symlink at a predictable session path or read
 // the bridge files. Both hooks derive the same dir from the same uid, so the
@@ -135,6 +174,7 @@ function main() {
   process.stdin.on('end', () => {
     try {
       const data = JSON.parse(input);
+      if (deferToClaudeRegistration(data.cwd || process.cwd())) process.exit(0);
       const sessionId = data.session_id;
 
       if (!sessionId) {
@@ -199,6 +239,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  deferToClaudeRegistration,
   buildContextWarning,
   bridgeDir,
   WARNING_THRESHOLD,

package/hooks/dist/pan-cost-logger.js

@@ -17,6 +17,45 @@
 
 const fs = require('fs');
 const path = require('path');
+
+// ─── R39: one run per hook when Claude and Copilot share a project ───────────
+// Copilot CLI also runs the hooks in a repository's .claude/settings.json and
+// .claude/settings.local.json. Measured 2026-09-26 (Copilot CLI 1.0.88, repository
+// hooks loaded): in a project with both the Claude and the Copilot install, every
+// PAN hook ran twice under Copilot — once from .github/hooks/pan.json, once from the
+// Claude settings. The Copilot project copy (this file under .github/hooks) steps
+// aside whenever the project's Claude settings register the same script, so the hook
+// runs once, and runs again from here the moment the Claude registration is gone.
+// Both files are repository hooks to Copilot and load under the same trust rule, so
+// deferring never leaves zero. Only this copy defers: Claude Code never reads
+// .github/hooks, Gemini and Codex never read .claude/settings.json, and a global
+// Copilot copy loads where repository hooks may not. Identical in every hook
+// Copilot registers — tests/copilot-hook-dedupe.test.cjs pins the copies.
+function deferToClaudeRegistration(projectDir, hookFile = __filename) {
+  // Assembled, not written as a literal: the installer rewrites every quoted .claude
+  // literal in a hook copy to that runtime's own directory, and this one must stay Claude's.
+  const claudeDir = ['.', 'claude'].join('');
+  try {
+    const hooksDir = path.dirname(hookFile);
+    if (path.basename(hooksDir) !== 'hooks' || path.basename(path.dirname(hooksDir)) !== '.github') return false;
+    if (typeof projectDir !== 'string' || !projectDir) return false;
+    const script = path.basename(hookFile);
+    for (const name of ['settings.json', 'settings.local.json']) {
+      let settings;
+      try { settings = JSON.parse(fs.readFileSync(path.join(projectDir, claudeDir, name), 'utf8')); } catch { continue; }
+      const events = settings && typeof settings.hooks === 'object' ? settings.hooks : null;
+      if (!events) continue;
+      for (const groups of Object.values(events)) {
+        if (!Array.isArray(groups)) continue;
+        for (const group of groups) {
+          const handlers = group && Array.isArray(group.hooks) ? group.hooks : [];
+          if (handlers.some((h) => h && typeof h.command === 'string' && h.command.includes(script))) return true;
+        }
+      }
+    }
+  } catch { /* fail open: run this copy */ }
+  return false;
+}
 const crypto = require('crypto');
 
 // Runtime config dirs a local PAN install lands in (mirrors installer getDirName).
@@ -182,7 +221,7 @@ function readActiveSessionMeta(cwd) {
 const COMMAND_TAIL_BYTES = 262144;
 
 // PAN's own command namespace, as a runtime writes it: `/pan:exec-phase` (Claude Code,
-// Gemini) or `/pan-exec-phase` (Codex, OpenCode, Copilot). Only these spawn PAN agents,
+// Gemini) or `/pan-exec-phase` (Codex, OpenCode, Copilot, and Claude Code after --unified-skills). Only these spawn PAN agents,
 // so only these are attributed — a host UI command (`/model`, `/compact`) and a plain
 // typed prompt leave the row honestly unattributed instead of borrowing a name.
 const PAN_COMMAND_RE = /<command-name>\s*\/?pan[:-]([a-z0-9][a-z0-9-]*)\s*<\/command-name>/i;
@@ -564,6 +603,8 @@ function buildCostRecord(data, cwd) {
   let outputTokens = 0;
   let cacheRead = 0;
   let cacheWrite = 0;
+  // { h1, m5 } when the source carried the cache-write lifetime split (M13).
+  let ttlSplit = null;
   let durationMs = null;
   // token_source records WHICH path produced the counts: `agent-transcript` (the
   // subagent's own conversation file — see resolveAgentTranscript), `transcript`
@@ -621,6 +662,10 @@ function buildCostRecord(data, cwd) {
     cacheWrite = clampSlice(rawCw, SLICE_MAX.cache_write);
     clamped = rawIn > SLICE_MAX.input || rawOut > SLICE_MAX.output
       || rawCr > SLICE_MAX.cache_read || rawCw > SLICE_MAX.cache_write;
+    // A clamped write total no longer matches its split, so the split is dropped with it.
+    if (typeof fromTranscript.cache_write_1h_tokens === 'number' && rawCw <= SLICE_MAX.cache_write) {
+      ttlSplit = { h1: fromTranscript.cache_write_1h_tokens, m5: fromTranscript.cache_write_5m_tokens || 0 };
+    }
     durationMs = durationFromSpan(fromTranscript.first_ts, fromTranscript.last_ts); // as measured — see SLICE_MAX
     if (!model) model = fromTranscript.model;
     if (fromTranscript.lineCount > since) {
@@ -676,6 +721,11 @@ function buildCostRecord(data, cwd) {
     cacheRead = clampPlausible(rawCr);
     cacheWrite = clampPlausible(rawCw);
     clamped = [rawIn, rawOut, rawCr, rawCw].some((n) => n > PLAUSIBLE_MAX);
+    const split = {};
+    addCacheTtlSplit(split, data.usage);
+    if (typeof split.cache_write_1h_tokens === 'number' && cacheWrite === rawCw) {
+      ttlSplit = { h1: clampPlausible(split.cache_write_1h_tokens), m5: clampPlausible(split.cache_write_5m_tokens) };
+    }
   }
 
   // Backfill command/phase from the active trace session when the payload omits
@@ -705,6 +755,8 @@ function buildCostRecord(data, cwd) {
     output_tokens: outputTokens,
     cache_read_tokens: cacheRead,
     cache_write_tokens: cacheWrite,
+    // The lifetime split of cache_write_tokens, present only when measured (M13).
+    ...(ttlSplit ? { cache_write_1h_tokens: ttlSplit.h1, cache_write_5m_tokens: ttlSplit.m5 } : {}),
     cost_usd: null,
     duration_ms: durationMs,
     phase,
@@ -833,11 +885,27 @@ function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
     totals.output_tokens += extractNumber(usage, 'output_tokens');
     totals.cache_read_input_tokens += extractNumber(usage, 'cache_read_input_tokens');
     totals.cache_creation_input_tokens += extractNumber(usage, 'cache_creation_input_tokens');
+    addCacheTtlSplit(totals, usage);
   }
   totals.lineCount = seen;
   return totals;
 }
 
+/**
+ * Add a usage record's cache-write lifetime split to `totals` (M13). Claude Code
+ * transcripts carry `usage.cache_creation: { ephemeral_5m_input_tokens,
+ * ephemeral_1h_input_tokens }` beside the `cache_creation_input_tokens` total;
+ * one-hour writes bill at 2x base input against 1.25x for five-minute ones, so
+ * the ledger keeps the split. The totals gain the two fields only when some
+ * record carried the block — rows from hosts without it stay unchanged.
+ */
+function addCacheTtlSplit(totals, usage) {
+  const cc = usage && usage.cache_creation;
+  if (!cc || typeof cc !== 'object') return;
+  totals.cache_write_1h_tokens = (totals.cache_write_1h_tokens || 0) + extractNumber(cc, 'ephemeral_1h_input_tokens');
+  totals.cache_write_5m_tokens = (totals.cache_write_5m_tokens || 0) + extractNumber(cc, 'ephemeral_5m_input_tokens');
+}
+
 /**
  * Append record to .planning/metrics/tokens.jsonl. Silently succeeds
  * even if the file or directory can't be written — hook must not block.
@@ -922,6 +990,7 @@ if (require.main === module) {
       // fall back to process.cwd() which is the project root when Claude Code
       // invokes the hook.
       const cwd = data.cwd || data.workspace?.current_dir || process.cwd();
+      if (deferToClaudeRegistration(cwd)) return;
       // M62: a global-install hook fires in every repo; don't pollute non-PAN
       // projects with .planning/ metrics artifacts. The tree must already exist —
       // see hasPlanningTree (field sweep 2026-09-17).
@@ -934,4 +1003,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, resolveAgentTranscript, readCursor, writeCursor, isPanProject, hasPlanningTree, readCommandFromTranscript, isSessionStale, PAN_RUNTIME_DIRS, METRICS_DIR, TOKENS_FILE, CURSOR_FILE, SLICE_MAX, MAX_CURSOR_KEYS };
+module.exports = { deferToClaudeRegistration, buildCostRecord, appendRecord, readUsageFromTranscript, addCacheTtlSplit, resolveAgentTranscript, readCursor, writeCursor, isPanProject, hasPlanningTree, readCommandFromTranscript, isSessionStale, PAN_RUNTIME_DIRS, METRICS_DIR, TOKENS_FILE, CURSOR_FILE, SLICE_MAX, MAX_CURSOR_KEYS };

package/hooks/dist/pan-state-reinject.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+// State Re-injection - SessionStart hook, `compact` matcher (market-ideas queue M10)
+//
+// Compaction replaces the conversation with a summary, and a summary can drop the
+// one line that mattered: which phase is in flight, which plan, where it stopped.
+// The PanLoop boundary-drop class (finding 0) is that failure — an agent that no
+// longer knows it is mid-chain ends the turn or re-plans finished work. This hook
+// runs when the session restarts after a compaction and hands the model PAN's
+// current position, read from the planning tree on disk, as `additionalContext`.
+//
+// Why SessionStart and not PostCompact: Claude Code's PostCompact has no decision
+// control and discards its output ("Used for side effects like logging"), while
+// SessionStart fires again after a compaction with `source: "compact"` and honours
+// `hookSpecificOutput.additionalContext` (code.claude.com/docs/en/hooks, read
+// 2026-09-26). Codex is the same: its PostCompact output schema has no
+// additionalContext, and SessionStart hooks matching `source: "compact"` deliver it
+// to the continuation (codex hooks docs, read 2026-09-26). Registered with the
+// `compact` matcher on both; the source is re-checked here so a registration
+// without the matcher stays inert on every other start.
+//
+// Inert unless the project is a PAN project with work in flight: `.planning/`
+// holds a state.md that names a current phase AND a roadmap.md with an unticked
+// phase. Everywhere else — no planning tree, a focus-only project, a finished
+// milestone — it prints nothing. It never writes a file (field finding: hooks
+// that scaffolded `.planning/` in projects that never ran PAN).
+//
+// Fail-open everywhere: bad stdin, unreadable files — exit 0 silently. A missing
+// reminder costs a re-read; a crashed hook is a failing hook at every start.
+//
+// The block is capped well under the host's 10,000-character limit for
+// additionalContext; each field is truncated on its own.
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Which planning tree this hook acts on.
+ *
+ * Mirrors pan-wizard-core/bin/lib/planning-root.cjs, which hooks cannot require
+ * (they are standalone and run inside the host runtime). All PAN hooks carry an
+ * identical copy — if the CLI is pointed at a track while a hook still writes to
+ * `.planning/`, that tree's telemetry lands in the wrong place.
+ *
+ * Env only — a hook gets no argv. A value that escapes the project root is
+ * ignored rather than honoured: a bad value degrades to the default, never
+ * writes outside the project.
+ */
+function planningDirName() {
+  const raw = process.env.PAN_PLANNING_DIR || '';
+  if (raw.trim()) {
+    const rel = raw.trim().replace(/\\/g, '/');
+    const bad = rel.startsWith('/') || rel.startsWith('\\') || /^[A-Za-z]:/.test(rel)
+      || rel.split('/').includes('..');
+    if (!bad) return rel;
+  }
+  const track = (process.env.PAN_TRACK || '').trim();
+  if (track && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(track)) {
+    return `.planning/tracks/${track}`;
+  }
+  return '.planning';
+}
+
+/** Absolute path inside the active planning tree. */
+function planningPath(cwd, ...segments) {
+  return path.join(cwd, ...planningDirName().split('/'), ...segments);
+}
+
+// Same unticked-phase shape the stop guard and the PanLoop harness use: the
+// checklist line templates/roadmap.md and pan-roadmapper.md emit.
+const UNTICKED_PHASE_RE = /^- \[ \] \*\*Phase (\d+(?:\.\d+)?):/m;
+
+const FIELD_MAX = 240;
+const BLOCK_MAX = 2000;
+
+/** A `**Name:** value` field from state.md — the shape state.cjs reads and writes. */
+function field(content, name) {
+  const m = content.match(new RegExp(`\\*\\*${name}:\\*\\*[ \\t]*(.+)`, 'i'));
+  if (!m) return null;
+  const v = m[1].trim();
+  // Template placeholders ("[X]", "[Phase name]") are not a position.
+  if (!v || /^\[.*\]$/.test(v) || /^none$/i.test(v)) return null;
+  return v.length > FIELD_MAX ? v.slice(0, FIELD_MAX - 1) + '…' : v;
+}
+
+/**
+ * Pure: the additionalContext block for this planning tree, or null when there is
+ * nothing in flight to restore.
+ * @param {object} args
+ * @param {string|null} args.stateContent   .planning/state.md, or null
+ * @param {string|null} args.roadmapContent .planning/roadmap.md, or null
+ * @param {string} [args.planningRel]       the planning directory, for the pointer line
+ * @returns {string|null}
+ */
+function buildReinjectContext({ stateContent, roadmapContent, planningRel = '.planning' }) {
+  if (typeof stateContent !== 'string' || typeof roadmapContent !== 'string') return null;
+  const phase = field(stateContent, 'Current Phase');
+  if (!phase) return null;
+  const unticked = roadmapContent.match(UNTICKED_PHASE_RE);
+  if (!unticked) return null; // every roadmap phase is built — nothing in flight
+
+  const name = field(stateContent, 'Current Phase Name');
+  const plan = field(stateContent, 'Current Plan');
+  const plans = field(stateContent, 'Total Plans in Phase');
+  const status = field(stateContent, 'Status');
+  const stoppedAt = field(stateContent, 'Stopped At');
+  const lastDesc = field(stateContent, 'Last Activity Description');
+  const resume = field(stateContent, 'Resume File');
+
+  const lines = ['PAN project state, re-read from disk after context compaction:'];
+  let position = `- Current phase: ${phase}${name ? ` (${name})` : ''}`;
+  if (plan) position += `, plan ${plan}${plans ? ` of ${plans}` : ''}`;
+  lines.push(position);
+  if (status) lines.push(`- Status: ${status}`);
+  if (stoppedAt) lines.push(`- Stopped at: ${stoppedAt}`);
+  else if (lastDesc) lines.push(`- Last activity: ${lastDesc}`);
+  if (resume) lines.push(`- Resume file: ${resume}`);
+  lines.push(`- First unbuilt roadmap phase: Phase ${unticked[1]}`);
+  lines.push(`Re-read ${planningRel}/state.md and the current phase's plan before the next step: continue the work in flight rather than re-planning finished work.`);
+  const block = lines.join('\n');
+  return block.length > BLOCK_MAX ? block.slice(0, BLOCK_MAX - 1) + '…' : block;
+}
+
+function readIfExists(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function main() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      let payload = {};
+      try { payload = JSON.parse(input); } catch { /* fail open on bad stdin */ }
+      if (!payload || typeof payload !== 'object') payload = {};
+      if (payload.source !== 'compact') { process.exit(0); return; }
+
+      const projectDir = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+      const context = buildReinjectContext({
+        stateContent: readIfExists(planningPath(projectDir, 'state.md')),
+        roadmapContent: readIfExists(planningPath(projectDir, 'roadmap.md')),
+        planningRel: planningDirName(),
+      });
+      if (context) {
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
+        }));
+      }
+    } catch { /* fail open — never break a session start */ }
+    process.exit(0);
+  });
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { buildReinjectContext, UNTICKED_PHASE_RE };