llm-wiki-kit 0.2.8 → 0.2.9

package/README.md

@@ -86,11 +86,12 @@ Use Claude Code or Codex normally.
 
 The installed hooks:
 
-- inject functional compact context at session start, instructions loaded, prompt submit, and post-compact time. The hook still uses `wiki/memory.md`, `wiki/index.md`, relevant wiki search results, maintenance signals, and update status; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
+- inject functional compact context at session start, instructions loaded, and prompt submit. The hook still uses `wiki/memory.md`, `wiki/index.md`, relevant wiki search results, maintenance signals, update status, and any compact recovery packet; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
 - 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
+- after compaction, store the redacted compact summary only; if pre-compact preservation failed, prepare a recovery packet for the next legal model-visible context hook
 - 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
@@ -101,7 +102,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.
+Pre-compact preservation always lets compaction proceed. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` suppresses failure warnings; `limited` and `soft` both emit a non-blocking warning if checkpoint storage fails. The hook 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 or recovery packet is written.
 
 ## Operational Commands
 

package/docs/integrations/claude-code.md

@@ -44,12 +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` 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.
+`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`. Compaction is not blocked; if checkpoint storage fails, the hook records a compact recovery packet for the next legal context-injection event. `PostCompact` stores the redacted compact summary as a context note and prepares any pending recovery packet without returning model-visible context directly. 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.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` to suppress pre-compact failure warnings; `limited` and `soft` both keep compaction moving and emit a non-blocking warning when checkpoint/queue preservation fails. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the bounded tail size.
 
 After installation or update, run:
 

package/docs/integrations/codex.md

@@ -33,8 +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` 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.
+- `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`. Compaction is not blocked; if checkpoint storage fails, the hook records a compact recovery packet for the next legal context-injection event.
+- `PostCompact` stores the redacted compact summary as a context note and prepares any pending compact recovery packet. It does not return `hookSpecificOutput.additionalContext`, because Codex `PostCompact` only supports common output fields.
 - 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.
@@ -44,7 +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.
+Set `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` to suppress pre-compact failure warnings; `limited` and `soft` both keep compaction moving and emit a non-blocking warning 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

@@ -62,8 +62,8 @@ 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 후보를 남긴다.
+- session start, instructions loaded, prompt submit 시점에 functional compact context를 주입한다. `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과, maintenance signal, update status, compact recovery packet은 계속 사용하되 사용자 화면에 보일 수 있는 hook context는 필요한 정보 중심으로 정제한다.
+- pre compact 시점에는 현재 turn을 분류하고, simple turn은 context note만 남기며, meaningful/durable turn은 redacted live Q&A checkpoint와 필요한 maintenance queue 후보를 남긴다. 저장 실패 시에도 compact는 진행시키고, 중요한 내용만 recovery packet으로 준비한다.
 - 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 자동 생성하지 않는다.
@@ -387,9 +387,9 @@ Claude Code handled events:
 
 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 정책과 별도로 유지한다.
+Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는다. memory hot index, navigation index, relevant wiki hits, link expansion, maintenance signal, passive runtime update status, compact recovery packet을 계속 사용할 수 있고, 사용자 화면에 보일 수 있는 `additionalContext`만 functional compact context로 정제한다. `PostCompact`는 compact summary 저장과 recovery packet 준비만 수행하고 model-visible 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 한도를 조정한다.
+Pre-compact 보존은 compact를 block하지 않는다. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off`는 실패 warning을 억제하고, `limited`/`soft`는 checkpoint/queue 저장 실패 시 non-blocking warning만 남긴다. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`로 transcript tail byte 한도를 조정한다.
 
 ## Security Defaults
 

package/docs/operations.md

@@ -143,9 +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`. `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.
+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. If checkpoint storage fails, compaction still proceeds and the hook prepares an important-only compact recovery packet for the next legal context-injection event. `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.
+Pre-compact preservation defaults to `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`, but compaction is never blocked by llm-wiki-kit. `limited` and `soft` emit non-blocking failure warnings, 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/package.json

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

package/src/compact-capture.js

@@ -4,26 +4,12 @@ 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';
+import { buildEntryFromState, clearCompactRecovery, readCompactRecovery, writeCompactRecovery } 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';
@@ -118,16 +104,77 @@ function entryWithTranscriptTail(entry, tail) {
   return next;
 }
 
-function failureOutput(provider, eventName, message, mode) {
+function captured(value) {
+  const text = String(value || '').trim();
+  return text && text !== '(not captured)' ? text : '';
+}
+
+function sanitizeFailureText(projectRoot, value) {
+  let text = String(value || '');
+  if (projectRoot) text = text.split(projectRoot).join('[REDACTED:project-root]');
+  return summarizeForStorage(text, 1200);
+}
+
+function sanitizeFailures(projectRoot, failures) {
+  return failures.map((failure) => sanitizeFailureText(projectRoot, failure));
+}
+
+function formatRecoveryContext(recovery) {
+  const entry = recovery?.entry || {};
+  const lines = [
+    'LLM Wiki compact recovery:',
+    '- PreCompact preservation could not finish before compaction. Use this fallback context only for important lost details.',
+    `- classification: ${recovery?.classification || 'unknown'}`,
+  ];
+  if (recovery?.postCompactSummary) {
+    lines.push(`- compact summary: ${summarizeForStorage(recovery.postCompactSummary, 600)}`);
+  }
+  if (recovery?.failures) {
+    lines.push(`- preservation failure: ${summarizeForStorage(recovery.failures, 600)}`);
+  }
+  const fields = [
+    ['question', 'question', 900],
+    ['work', 'work', 1200],
+    ['result', 'result', 1400],
+    ['changedFiles', 'changed files', 700],
+    ['verification', 'verification', 700],
+    ['followUp', 'follow-up', 700],
+  ];
+  for (const [key, label, limit] of fields) {
+    const value = captured(entry[key]);
+    if (value) lines.push(`\n${label}:\n${summarizeForStorage(value, limit)}`);
+  }
+  return summarizeForStorage(lines.join('\n'), 5000);
+}
+
+async function recordCompactRecoveryFailure(projectRoot, payload, entry, classification, failures) {
+  const recovery = {
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    classification: classification.kind,
+    failures: summarizeForStorage(failures.join('; '), 1200),
+    entry: {
+      topic: summarizeForStorage(entry.topic, 300),
+      question: summarizeForStorage(entry.question, 1000),
+      work: summarizeForStorage(entry.work, 1600),
+      result: summarizeForStorage(entry.result, 1800),
+      changedFiles: summarizeForStorage(entry.changedFiles, 900),
+      verification: summarizeForStorage(entry.verification, 900),
+      followUp: summarizeForStorage(entry.followUp, 900),
+      firstTimestamp: entry.firstTimestamp,
+      session: entry.session,
+    },
+  };
+  recovery.context = formatRecoveryContext(recovery);
+  await writeCompactRecovery(projectRoot, payload, recovery);
+}
+
+function failureOutput(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}`);
+  return {
+    systemMessage: `LLM Wiki PreCompact preservation warning: ${reason}`,
+  };
 }
 
 export async function handlePreCompactCapture(projectRoot, provider, eventName, payload) {
@@ -193,12 +240,16 @@ export async function handlePreCompactCapture(projectRoot, provider, eventName,
   }
 
   if (failures.length > 0) {
-    return failureOutput(
-      provider,
-      eventName,
-      `LLM Wiki PreCompact preservation did not complete. ${failures.join('; ')}`,
-      mode
-    );
+    let safeFailures = sanitizeFailures(projectRoot, failures);
+    if (classification.archive) {
+      try {
+        await recordCompactRecoveryFailure(projectRoot, payload, entry, classification, safeFailures);
+      } catch (error) {
+        failures.push(`compact recovery marker failed: ${error?.message || error}`);
+        safeFailures = sanitizeFailures(projectRoot, failures);
+      }
+    }
+    return failureOutput(`LLM Wiki PreCompact preservation did not complete. ${safeFailures.join('; ')}`, mode);
   }
 
   return {};
@@ -212,3 +263,30 @@ export async function recordPostCompactSummary(projectRoot, eventName, payload)
     summary ? `Compact summary:\n${redactText(summary, 4000)}` : 'Compact summary was not provided.'
   );
 }
+
+export async function finalizeCompactRecovery(projectRoot, payload) {
+  const recovery = await readCompactRecovery(projectRoot, payload);
+  if (!recovery) return null;
+  const summary = compactSummaryText(payload);
+  const next = {
+    ...recovery,
+    updated_at: new Date().toISOString(),
+    postCompactSummary: summary || recovery.postCompactSummary || '',
+    ready: true,
+  };
+  next.context = formatRecoveryContext(next);
+  await writeCompactRecovery(projectRoot, payload, next);
+  await appendContextNote(
+    projectRoot,
+    'PostCompact',
+    'Prepared compact recovery packet for the next legal model-visible hook context.'
+  ).catch(() => {});
+  return next;
+}
+
+export async function consumeCompactRecoveryContext(projectRoot, payload) {
+  const recovery = await readCompactRecovery(projectRoot, payload);
+  if (!recovery) return '';
+  await clearCompactRecovery(projectRoot, payload);
+  return recovery.context || formatRecoveryContext(recovery);
+}

package/src/hook.js

@@ -1,7 +1,7 @@
 import { findProjectRoot } from './fs-utils.js';
 import { classifyTurn, formatDurableCaptureGuidance, hasDetectedDurableWikiChange, isLegacyEagerCaptureMode } from './capture-policy.js';
 import { bootstrapProject, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
-import { compactSummaryText, handlePreCompactCapture, recordPostCompactSummary } from './compact-capture.js';
+import { consumeCompactRecoveryContext, finalizeCompactRecovery, handlePreCompactCapture, recordPostCompactSummary } from './compact-capture.js';
 import { recoverStaleTurnStates, recordMaintenanceForEntry } from './maintenance.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { recordProject } from './projects.js';
@@ -35,8 +35,16 @@ function toolSummary(payload) {
   return `${toolName}: ${summarizeForStorage(input, 1200)}`;
 }
 
-function contextOutput(eventName, context) {
+function supportsAdditionalContext(provider, eventName) {
+  const normalized = String(provider || '').toLowerCase();
+  if (normalized === 'codex') return ['SessionStart', 'UserPromptSubmit'].includes(eventName);
+  if (normalized === 'claude') return ['SessionStart', 'InstructionsLoaded', 'UserPromptSubmit'].includes(eventName);
+  return ['SessionStart', 'InstructionsLoaded', 'UserPromptSubmit'].includes(eventName);
+}
+
+function contextOutput(provider, eventName, context) {
   if (!context) return {};
+  if (!supportsAdditionalContext(provider, eventName)) return {};
   return {
     hookSpecificOutput: {
       hookEventName: eventName,
@@ -129,21 +137,30 @@ export async function handleHook(provider, explicitEvent) {
   }
 
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded') {
-    const context = await hookContext(projectRoot, eventName, await buildContextBrief(projectRoot, 'SessionStart'), payload);
-    return contextOutput(eventName, context);
+    const recovery = supportsAdditionalContext(provider, eventName)
+      ? await consumeCompactRecoveryContext(projectRoot, payload).catch(() => '')
+      : '';
+    const context = await hookContext(
+      projectRoot,
+      eventName,
+      [recovery, await buildContextBrief(projectRoot, 'SessionStart')].filter(Boolean).join('\n\n'),
+      payload
+    );
+    return contextOutput(provider, eventName, context);
   }
 
   if (eventName === 'UserPromptSubmit') {
     const prompt = promptText(payload);
     await rememberQuestion(projectRoot, payload, prompt);
     const guidance = formatDurableCaptureGuidance(prompt);
+    const recovery = await consumeCompactRecoveryContext(projectRoot, payload).catch(() => '');
     const context = await hookContext(
       projectRoot,
       eventName,
-      [await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n'),
+      [recovery, await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n'),
       payload
     );
-    return contextOutput(eventName, context);
+    return contextOutput(provider, eventName, context);
   }
 
   if (eventName === 'PreToolUse') {
@@ -158,10 +175,9 @@ export async function handleHook(provider, explicitEvent) {
 
   if (eventName === 'PreCompact' || eventName === 'PostCompact') {
     if (eventName === 'PostCompact') {
-      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);
+      await finalizeCompactRecovery(projectRoot, payload).catch(() => {});
+      return {};
     }
     return handlePreCompactCapture(projectRoot, provider, eventName, payload);
   }

package/src/state.js

@@ -38,6 +38,22 @@ export async function clearTurnState(projectRoot, payload) {
   await unlink(statePath(projectRoot, payload)).catch(() => {});
 }
 
+export function compactRecoveryPath(projectRoot, payload) {
+  return join(kitDataDir(), 'compact-recovery', `${sessionKey(projectRoot, payload)}.json`);
+}
+
+export async function readCompactRecovery(projectRoot, payload) {
+  return readJson(compactRecoveryPath(projectRoot, payload), null);
+}
+
+export async function writeCompactRecovery(projectRoot, payload, recovery) {
+  await writeJson(compactRecoveryPath(projectRoot, payload), recovery);
+}
+
+export async function clearCompactRecovery(projectRoot, payload) {
+  await unlink(compactRecoveryPath(projectRoot, payload)).catch(() => {});
+}
+
 export async function rememberQuestion(projectRoot, payload, prompt) {
   const state = await readTurnState(projectRoot, payload);
   const clean = summarizeForStorage(prompt, 3000);