llm-wiki-kit 0.2.7 → 0.2.8

package/README.md

@@ -90,6 +90,7 @@ The installed hooks:
 - remove Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` surfaces at session start so `llm-wiki/` remains the active wiki implementation
 - record small redacted raw event envelopes and per-turn state
 - capture decision points, debugging findings, changed files, and verification notes
+- before compaction, classify the current turn and save a redacted checkpoint for meaningful or durable work; durable candidates also get a maintenance queue item
 - allow tool calls to proceed without secret/PII-based hook blocking
 - update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md` only for meaningful work turns
 - avoid automatic `wiki/queries/` and `wiki/decisions/` promotion in the default answer-first mode
@@ -100,6 +101,7 @@ The installed hooks:
 
 If you need to think about saving every answer manually, the setup has failed.
 If wiki maintenance delays the actual answer, the setup is being used wrong. The default capture mode is `LLM_WIKI_KIT_CAPTURE_MODE=answer-first`; the old eager query/decision capture path remains only as deprecated compatibility mode via `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager`.
+Pre-compact preservation uses `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited|soft|off` with default `limited`. It reads only a bounded transcript tail controlled by `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`; the raw transcript path and authentication values are redacted before any checkpoint is written.
 
 ## Operational Commands
 
@@ -171,6 +173,7 @@ llm-wiki hook claude Stop
 ## Security Defaults
 
 - Full raw transcript capture is disabled by default.
+- PreCompact may read a small bounded transcript tail to create a redacted checkpoint, but it does not store the full transcript or raw `transcript_path`.
 - Tool calls are not blocked only because inputs look sensitive.
 - Authentication values such as tokens, passwords, and private keys are redacted before durable summaries are written.
 - Hook payloads are stored only as redacted event envelopes.

package/docs/integrations/claude-code.md

@@ -44,11 +44,12 @@ The hook records redacted turn summaries but does not deny tool calls only becau
 
 At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects functional compact context. The context still uses `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, relevant wiki/search state, operating rules, maintenance signals, passive runtime update status, and managed-template cleanup notes; the hook formats those signals so they are usable if shown in the Claude Code UI. At `UserPromptSubmit`, it recovers stale turn state, searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful functional compact context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 
-`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` records a compaction note, and `PostCompact` records the note and returns fresh wiki context. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
+`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` classifies the current turn before compaction: simple turns record only a context note, meaningful work writes a live Q&A checkpoint, and durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`. `PostCompact` stores the redacted compact summary as a context note and returns fresh wiki context. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached passive runtime update status.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited|soft|off` to tune pre-compact failure handling; default `limited` blocks only when checkpoint/queue preservation fails on providers with block support. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
 
 After installation or update, run:
 

package/docs/integrations/codex.md

@@ -33,7 +33,8 @@ Expected behavior:
 - `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful functional compact context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.
-- `PreCompact` records a compaction note; `PostCompact` records the note and returns fresh wiki context.
+- `PreCompact` classifies the current turn before compaction. Simple turns record only a context note; meaningful work writes a live Q&A checkpoint; durable candidates write both a checkpoint and a maintenance queue item. The checkpoint can include only a bounded redacted transcript tail, never the full raw transcript or raw `transcript_path`.
+- `PostCompact` stores the redacted compact summary as a context note and returns fresh wiki context.
 - In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` appends live Q&A only for meaningful work turns and does not auto-create `wiki/queries/` or `wiki/decisions/`.
 - If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop` queues a pending maintenance item for agent review.
 - `Stop` clears the per-session turn buffer after recording. `SubagentStop` leaves the parent turn buffer available for the final stop event.
@@ -43,6 +44,7 @@ Hook payloads are stored as small redacted event envelopes rather than full tran
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached passive runtime update status.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited|soft|off` to tune pre-compact failure handling; default `limited` blocks only on supported providers when checkpoint/queue preservation fails. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
 
 Run these after install:
 

package/docs/manual.md

@@ -63,6 +63,7 @@ llm-wiki/
 설치된 hook은 다음 일을 자동으로 수행한다.
 
 - session start, prompt submit, post compact 시점에 functional compact context를 주입한다. `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과, maintenance signal, update status는 계속 사용하되 사용자 화면에 보일 수 있는 hook context는 필요한 정보 중심으로 정제한다.
+- pre compact 시점에는 현재 turn을 분류하고, simple turn은 context note만 남기며, meaningful/durable turn은 redacted live Q&A checkpoint와 필요한 maintenance queue 후보를 남긴다.
 - prompt/tool/result summary를 redaction한 뒤 turn buffer에 기록한다.
 - 의미 있는 작업 turn만 `outputs/questions/YYYY-MM-DD-live-qa.md`에 live Q&A로 남긴다.
 - 기본 answer-first mode에서는 `wiki/queries/`와 `wiki/decisions/`를 매 turn 자동 생성하지 않는다.
@@ -384,10 +385,12 @@ Claude Code handled events:
 - `Stop`
 - `SessionEnd`
 
-Hook payload는 full transcript가 아니라 작은 redacted event envelope다. context output도 field별 redaction을 거친다.
+Hook payload는 full transcript가 아니라 작은 redacted event envelope다. context output도 field별 redaction을 거친다. `PreCompact`는 checkpoint 생성을 위해 작은 bounded transcript tail만 읽을 수 있고, 저장 전 인증값과 raw `transcript_path`를 redaction한다.
 
 Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는다. memory hot index, navigation index, relevant wiki hits, link expansion, maintenance signal, passive runtime update status를 계속 사용할 수 있고, 사용자 화면에 보일 수 있는 `additionalContext`만 functional compact context로 정제한다. `llm-wiki context` CLI의 full debug 출력은 이 hook formatting 정책과 별도로 유지한다.
 
+Pre-compact 보존은 기본 `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`로 동작한다. `limited`는 checkpoint/queue 저장 실패 시 block을 지원하는 provider에서만 compact block을 시도하고, 그 외에는 failure context를 남긴다. `soft`는 block하지 않고, `off`는 실패 output을 억제한다. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`로 transcript tail byte 한도를 조정한다.
+
 ## Security Defaults
 
 기본 정책은 aggressive blocking보다 useful local work wiki를 우선한다.
@@ -396,6 +399,7 @@ Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는
 - token, password, bearer credential, private key, `.env` 원문 같은 authentication value는 durable summary에 쓰기 전 redaction한다.
 - phone number, email, date, business identifier는 local work context로 유용할 수 있어 기본 보존한다.
 - full raw transcript capture는 기본 기능이 아니다.
+- `PreCompact` checkpoint는 bounded redacted transcript tail만 사용할 수 있으며 full transcript와 raw `transcript_path`는 저장하지 않는다.
 - `llm-wiki lint`는 wiki 안의 secret-like content를 error로 보고한다.
 
 민감한 raw command output, log, screenshot, transcript를 저장해야 할 때는 먼저 redaction한다. 인증값은 wiki, report, live Q&A, command history에 남기지 않는다.

package/docs/operations.md

@@ -143,7 +143,9 @@ After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working
 
 Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject context automatically, but the current user answer takes priority over wiki cleanup. The active agent updates durable wiki pages when reusable project knowledge appears and the turn's importance or user consent justifies persistence. Hook context policy is function-first: memory, search, maintenance, and update signals remain available, while user-visible context is formatted as functional compact context instead of a raw dump.
 
-In the default `LLM_WIKI_KIT_CAPTURE_MODE=answer-first` mode, `Stop` and `SessionEnd` append live Q&A only for meaningful work turns. They do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation and no durable wiki update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md`. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete. `SessionStart` injects a one-item queue summary; `UserPromptSubmit` injects a soft reminder only when the prompt is wiki/maintenance related or matches a queue topic. This is a recovery and reminder layer, not a full transcript capture path.
+In the default `LLM_WIKI_KIT_CAPTURE_MODE=answer-first` mode, `Stop` and `SessionEnd` append live Q&A only for meaningful work turns. They do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation and no durable wiki update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md`. `PreCompact` performs the same answer-first classification before context compaction: simple turns get only a context note, archive-worthy turns get a live Q&A checkpoint, and durable candidates get a checkpoint plus queue item. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete. `SessionStart` injects a one-item queue summary; `UserPromptSubmit` injects a soft reminder only when the prompt is wiki/maintenance related or matches a queue topic. This is a recovery and reminder layer, not a full transcript capture path.
+
+Pre-compact preservation defaults to `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`. In that mode, checkpoint/queue write failures can block compact only on providers that support hook blocking; otherwise the hook returns best-effort failure context. `soft` never blocks, and `off` suppresses failure output. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the small bounded transcript tail used for checkpoint context. Authentication values and the raw transcript path are redacted before storage.
 
 `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` keeps the old eager live Q&A/query/decision/maintenance behavior for compatibility only. New projects should rely on the answer-first default.
 

package/docs/security.md

@@ -13,4 +13,4 @@ Before writing durable summaries, the runtime redacts authentication values such
 
 Manual and hook context output also runs through redaction before returning excerpts or search hits. `llm-wiki lint` reports remaining secret-like wiki content as an error so it can be removed or rewritten before it becomes reusable project memory.
 
-Hook payloads are stored as small event envelopes, not full raw transcripts. Full transcript capture is intentionally not implemented as a default. If a project needs it, add a project-local policy and a redaction path first.
+Hook payloads are stored as small event envelopes, not full raw transcripts. Full transcript capture is intentionally not implemented as a default. `PreCompact` may read a small bounded transcript tail for a redacted checkpoint, but it does not store the raw transcript path or full transcript. If a project needs raw transcript capture, add a project-local policy and a redaction path first.

package/docs/troubleshooting.md

@@ -242,7 +242,7 @@ If the queue is always empty during ordinary Q&A, that is normal. If you expecte
 
 The hook does not block tool calls only because inputs look sensitive. Durable summaries redact authentication values before writing, while ordinary work context such as dates, phone numbers, emails, and business identifiers is preserved by default.
 
-Hook payloads are stored as small redacted event envelopes rather than full transcripts. Manual and hook context output is redacted before wiki excerpts or search hits are returned.
+Hook payloads are stored as small redacted event envelopes rather than full transcripts. `PreCompact` checkpoints may include a bounded redacted transcript tail, but the full transcript and raw `transcript_path` are not stored. Manual and hook context output is redacted before wiki excerpts or search hits are returned.
 
 ## Duplicate Pages Appear
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/compact-capture.js

@@ -0,0 +1,214 @@
+import { open, stat } from 'fs/promises';
+import { relative } from 'path';
+import { classifyTurn } from './capture-policy.js';
+import { recordMaintenanceForEntry } from './maintenance.js';
+import { appendContextNote, appendLiveQa, appendWikiLog } from './project.js';
+import { redactText, summarizeForStorage } from './redaction.js';
+import { buildEntryFromState } from './state.js';
+
+const DEFAULT_PRECOMPACT_TAIL_BYTES = 32 * 1024;
+const MAX_PRECOMPACT_TAIL_BYTES = 256 * 1024;
+const ENFORCEMENT_MODES = new Set(['limited', 'soft', 'off']);
+
+function contextOutput(eventName, context) {
+  if (!context) return {};
+  return {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: context,
+    },
+  };
+}
+
+function providerSupportsBlock(provider) {
+  return String(provider || '').toLowerCase() === 'claude';
+}
+
+export function preCompactEnforcementMode(env = process.env) {
+  const value = String(env.LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT || 'limited').toLowerCase();
+  return ENFORCEMENT_MODES.has(value) ? value : 'limited';
+}
+
+export function preCompactTranscriptTailBytes(env = process.env) {
+  const raw = env.LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES;
+  if (raw === undefined || raw === '') return DEFAULT_PRECOMPACT_TAIL_BYTES;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_PRECOMPACT_TAIL_BYTES;
+  return Math.min(Math.floor(parsed), MAX_PRECOMPACT_TAIL_BYTES);
+}
+
+export function compactSummaryText(payload) {
+  return summarizeForStorage(
+    payload.compact_summary ||
+      payload.compactSummary ||
+      payload.summary ||
+      payload.message ||
+      '',
+    4000
+  );
+}
+
+function transcriptPath(payload) {
+  return payload.transcript_path || payload.transcriptPath || '';
+}
+
+function redactTranscriptPath(text, path) {
+  let output = String(text || '');
+  if (path) output = output.split(path).join('[REDACTED:transcript-path]');
+  output = output.replace(/("transcript_path"\s*:\s*)"[^"]*"/gi, '$1"[REDACTED:transcript-path]"');
+  output = output.replace(/('transcript_path'\s*:\s*)'[^']*'/gi, "$1'[REDACTED:transcript-path]'");
+  output = output.replace(/\btranscript_path\s*=\s*[^\s"'`]+/gi, 'transcript_path=[REDACTED:transcript-path]');
+  return output;
+}
+
+async function readTranscriptTail(path, maxBytes) {
+  if (!path) return { ok: false, reason: 'missing-transcript-path', text: '' };
+  if (maxBytes <= 0) return { ok: false, reason: 'transcript-tail-disabled', text: '' };
+
+  let handle = null;
+  try {
+    const info = await stat(path);
+    if (!info.isFile()) return { ok: false, reason: 'transcript-not-file', text: '' };
+    const length = Math.min(info.size, maxBytes);
+    const start = Math.max(0, info.size - length);
+    const buffer = Buffer.alloc(length);
+    handle = await open(path, 'r');
+    await handle.read(buffer, 0, length, start);
+    const text = summarizeForStorage(redactTranscriptPath(buffer.toString('utf8'), path), 4000);
+    return {
+      ok: true,
+      text,
+      bytesRead: length,
+      truncated: info.size > maxBytes,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: summarizeForStorage(error?.code || error?.message || 'read-failed', 200),
+      text: '',
+    };
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+function appendToField(current, addition) {
+  const existing = String(current || '').trim();
+  if (!existing || existing === '(not captured)') return addition;
+  return `${existing}\n${addition}`;
+}
+
+function entryWithTranscriptTail(entry, tail) {
+  const next = { ...entry };
+  if (tail.ok && tail.text) {
+    const marker = tail.truncated
+      ? 'PreCompact transcript tail (redacted bounded excerpt; earlier transcript omitted):'
+      : 'PreCompact transcript tail (redacted bounded excerpt):';
+    next.result = appendToField(next.result, `${marker}\n${tail.text}`);
+    next.followUp = appendToField(
+      next.followUp,
+      'Compact checkpoint includes only a bounded redacted transcript tail, not the raw transcript path or full transcript.'
+    );
+  } else if (tail.reason && tail.reason !== 'missing-transcript-path') {
+    next.followUp = appendToField(
+      next.followUp,
+      `Transcript tail unavailable during PreCompact (${tail.reason}); checkpoint used turn state only.`
+    );
+  }
+  return next;
+}
+
+function failureOutput(provider, eventName, message, mode) {
+  if (mode === 'off') return {};
+  const reason = summarizeForStorage(message, 1200);
+  if (mode === 'limited' && providerSupportsBlock(provider)) {
+    return {
+      decision: 'block',
+      reason,
+    };
+  }
+  return contextOutput(eventName, `LLM Wiki PreCompact preservation warning:\n${reason}`);
+}
+
+export async function handlePreCompactCapture(projectRoot, provider, eventName, payload) {
+  const mode = preCompactEnforcementMode();
+  const failures = [];
+  const tail = await readTranscriptTail(transcriptPath(payload), preCompactTranscriptTailBytes());
+  const stateEntry = await buildEntryFromState(projectRoot, payload, payload.last_assistant_message || payload.response || '');
+  const entry = entryWithTranscriptTail(stateEntry, tail);
+  const classification = classifyTurn(entry, eventName);
+
+  await appendContextNote(
+    projectRoot,
+    eventName,
+    [
+      `PreCompact classification: ${classification.kind}.`,
+      tail.ok ? `Transcript tail bytes read: ${tail.bytesRead}.` : `Transcript tail: ${tail.reason || 'not available'}.`,
+      'Turn state is intentionally kept for the later Stop/SessionEnd hook.',
+    ].join('\n')
+  ).catch((error) => {
+    failures.push(`context note failed: ${error?.message || error}`);
+  });
+
+  let liveQaPath = null;
+  if (classification.archive) {
+    const checkpointEntry = {
+      ...entry,
+      followUp: appendToField(
+        entry.followUp,
+        classification.suggestDurable
+          ? 'PreCompact saved this checkpoint and queued durable wiki review; merge reusable facts into existing wiki pages after the current answer.'
+          : 'PreCompact saved this checkpoint before context compaction; reusable facts should be merged only when appropriate.'
+      ),
+    };
+    try {
+      liveQaPath = await appendLiveQa(projectRoot, checkpointEntry);
+    } catch (error) {
+      failures.push(`live Q&A checkpoint failed: ${error?.message || error}`);
+    }
+  }
+
+  if (liveQaPath && ['suggest-durable', 'explicit-durable'].includes(classification.kind)) {
+    try {
+      const result = await recordMaintenanceForEntry(projectRoot, entry, {
+        source: liveQaPath,
+        eventName,
+        reason: 'PreCompact durable candidate checkpoint needs review after context compaction.',
+      });
+      if (result.created === false && result.reason) {
+        failures.push(`maintenance queue failed: ${result.reason}`);
+      }
+    } catch (error) {
+      failures.push(`maintenance queue failed: ${error?.message || error}`);
+    }
+  }
+
+  if (liveQaPath) {
+    await appendWikiLog(
+      projectRoot,
+      `precompact checkpoint; archive=${relative(projectRoot, liveQaPath)}; classification=${classification.kind}`
+    ).catch((error) => {
+      failures.push(`wiki log failed: ${error?.message || error}`);
+    });
+  }
+
+  if (failures.length > 0) {
+    return failureOutput(
+      provider,
+      eventName,
+      `LLM Wiki PreCompact preservation did not complete. ${failures.join('; ')}`,
+      mode
+    );
+  }
+
+  return {};
+}
+
+export async function recordPostCompactSummary(projectRoot, eventName, payload) {
+  const summary = compactSummaryText(payload);
+  await appendContextNote(
+    projectRoot,
+    eventName,
+    summary ? `Compact summary:\n${redactText(summary, 4000)}` : 'Compact summary was not provided.'
+  );
+}

package/src/hook.js

@@ -1,6 +1,7 @@
 import { findProjectRoot } from './fs-utils.js';
 import { classifyTurn, formatDurableCaptureGuidance, hasDetectedDurableWikiChange, isLegacyEagerCaptureMode } from './capture-policy.js';
-import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
+import { bootstrapProject, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
+import { compactSummaryText, handlePreCompactCapture, recordPostCompactSummary } from './compact-capture.js';
 import { recoverStaleTurnStates, recordMaintenanceForEntry } from './maintenance.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { recordProject } from './projects.js';
@@ -156,11 +157,13 @@ export async function handleHook(provider, explicitEvent) {
   }
 
   if (eventName === 'PreCompact' || eventName === 'PostCompact') {
-    await appendContextNote(projectRoot, eventName, 'Compaction lifecycle event captured by llm-wiki-kit.');
     if (eventName === 'PostCompact') {
-      return contextOutput(eventName, await buildContextBrief(projectRoot, eventName));
+      const summary = compactSummaryText(payload);
+      await recordPostCompactSummary(projectRoot, eventName, payload);
+      const context = await hookContext(projectRoot, eventName, await buildContextBrief(projectRoot, eventName, summary), payload);
+      return contextOutput(eventName, context);
     }
-    return {};
+    return handlePreCompactCapture(projectRoot, provider, eventName, payload);
   }
 
   if (eventName === 'Stop' || eventName === 'SubagentStop' || eventName === 'SessionEnd') {

package/src/install.js

@@ -19,6 +19,8 @@ import { bootstrapProject } from './project.js';
 import { recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageRoot, runtimeVersion } from './version.js';
 
+const SESSION_START_MATCHER = 'startup|resume|clear|compact';
+
 export function hookCommand(provider, eventName, options = {}) {
   return commandForNodeScript(binPath, ['hook', provider, eventName], options);
 }
@@ -125,11 +127,23 @@ async function reconcileWindowsCommand() {
 
 function addHook(hooks, eventName, command, options = {}) {
   hooks[eventName] = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
-  const already = hooks[eventName].some((entry) => (
+  const existing = hooks[eventName].find((entry) => (
     Array.isArray(entry?.hooks) &&
     entry.hooks.some((hook) => hook?.type === 'command' && hook?.command === command)
   ));
-  if (already) return false;
+  if (existing) {
+    let changed = false;
+    if (options.matcher && existing.matcher !== options.matcher) {
+      existing.matcher = options.matcher;
+      changed = true;
+    }
+    const hook = existing.hooks.find((item) => item?.type === 'command' && item?.command === command);
+    if (hook && options.commandWindows && hook.commandWindows !== options.commandWindows) {
+      hook.commandWindows = options.commandWindows;
+      changed = true;
+    }
+    return changed;
+  }
   const entry = {
     hooks: [
       {
@@ -186,12 +200,21 @@ function unsupportedKitClaudeEvents(hooks, supportedEvents) {
     .sort();
 }
 
-function hookTextIncludes(text, value) {
-  return normalizeHookPathText(text).includes(normalizeHookPathText(value));
+function expectedMatcher(eventName) {
+  return eventName === 'SessionStart' ? SESSION_START_MATCHER : undefined;
 }
 
-function hookEventIncludesBin(entries) {
-  return hookTextIncludes(JSON.stringify(entries || {}), binPath);
+function hookCommandMatches(hook, command) {
+  return hook?.command === command || hook?.commandWindows === command;
+}
+
+function hookEventIsCurrent(entries, eventName, command) {
+  const matcher = expectedMatcher(eventName);
+  return Array.isArray(entries) && entries.some((entry) => (
+    (!matcher || entry.matcher === matcher) &&
+    Array.isArray(entry?.hooks) &&
+    entry.hooks.some((hook) => hook?.type === 'command' && hookCommandMatches(hook, command))
+  ));
 }
 
 export async function install(options = {}) {
@@ -221,7 +244,7 @@ export async function install(options = {}) {
       changed.push('codex:replaced');
     }
     for (const eventName of CODEX_EVENTS) {
-      const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
+      const matcher = expectedMatcher(eventName);
       const command = hookCommand('codex', eventName, { platform });
       const commandWindows = isWindows({ platform }) ? hookCommand('codex', eventName, { platform: 'win32' }) : undefined;
       if (addHook(codex.hooks, eventName, command, { matcher, commandWindows })) {
@@ -251,7 +274,7 @@ export async function install(options = {}) {
       changed.push(...removedUnsupported.map((eventName) => `claude:removed-unsupported:${eventName}`));
     }
     for (const eventName of claudeEvents) {
-      const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
+      const matcher = expectedMatcher(eventName);
       if (addHook(claude.hooks, eventName, hookCommand('claude', eventName, { platform }), { matcher })) {
         claudeChanged = true;
         changed.push(`claude:${eventName}`);
@@ -312,9 +335,18 @@ export async function status(options = {}) {
   const claude = await readJson(claudeSettingsPath, {});
   const claudeDetection = detectClaudeVersion();
   const claudeEvents = supportedClaudeEvents(claudeDetection);
-  const claudeMissingEvents = claudeEvents.filter((eventName) => !hookEventIncludesBin(claude.hooks?.[eventName] || []));
+  const codexMissingEvents = CODEX_EVENTS.filter((eventName) => !hookEventIsCurrent(
+    codex.hooks?.[eventName] || [],
+    eventName,
+    hookCommand('codex', eventName, { platform })
+  ));
+  const claudeMissingEvents = claudeEvents.filter((eventName) => !hookEventIsCurrent(
+    claude.hooks?.[eventName] || [],
+    eventName,
+    hookCommand('claude', eventName, { platform })
+  ));
   const claudeUnsupportedKitEvents = unsupportedKitClaudeEvents(claude.hooks || {}, claudeEvents);
-  const codexInstalled = hookEventIncludesBin(codex.hooks || {});
+  const codexInstalled = codexMissingEvents.length === 0;
   const claudeInstalled = claudeMissingEvents.length === 0 && claudeUnsupportedKitEvents.length === 0;
   const discoveredCommandPaths = await findCommandPaths('llm-wiki', { platform });
   const commandPath = discoveredCommandPaths[0] || null;
@@ -344,6 +376,7 @@ export async function status(options = {}) {
     claudeVersion: claudeDetection.version || 'unknown',
     claudeModernHooks: claudeDetection.modern,
     claudeSupportedEvents: claudeEvents,
+    codexMissingEvents,
     claudeMissingEvents,
     claudeUnsupportedKitEvents,
     hooksCurrent: codexInstalled && claudeInstalled,