AGENTS.md

1# src/hooks/compaction-context-injector/ -- Post-Compaction Context Recovery
2 
3**Generated:** 2026-05-18
4 
5## OVERVIEW
6 
7Continuation Tier hook. Fires on `session.compacted` to re-inject critical context lost during context-window compaction. Prevents the agent from losing its bearings after OpenCode trims session history.
8 
9## TIER + EVENT
10 
11- **Tier:** Continuation
12- **Event:** `session.compacted` (primary), `session.idle`, `session.deleted`, `message.updated`, `message.part.delta`, `message.part.updated`
13 
14## KEY FILES
15 
16| File | Purpose |
17|------|---------|
18| `hook.ts` | `createCompactionContextInjector()` -- composes capture, restore, inject, event |
19| `recovery.ts` | `createRecoveryLogic()` -- rebuilds agent/model/tools after compaction |
20| `tail-monitor.ts` | Tracks assistant output to detect no-text tails |
21| `session-prompt-config-resolver.ts` | Walks session messages to resolve current agent/model/tools |
22| `validated-model.ts` | `validateCheckpointModel()` -- model validation |
23| `session-id.ts` | `resolveSessionID()`, `isCompactionAgent()` |
24| `recovery-prompt-config.ts` | `createExpectedRecoveryPromptConfig()`, `isPromptConfigRecovered()` |
25| `constants.ts` | `RECOVERY_COOLDOWN_MS`, `NO_TEXT_TAIL_THRESHOLD`, `RECENT_COMPACTION_WINDOW_MS` |
26| `types.ts` | `CompactionContextInjector` interface |
27| `compaction-context-prompt.ts` | `COMPACTION_CONTEXT_PROMPT` -- 8-section summary template |
28| `index.ts` / `index.test.ts` | Barrel export + tests |
29| `recovery.test.ts` / `session-prompt-config-resolver.test.ts` | Unit tests |
30 
31## HOW IT WORKS
32 
331. **Capture:** Before compaction, saves agent/model/tools checkpoint via `setCompactionAgentConfigCheckpoint()`
342. **Inject:** Returns `COMPACTION_CONTEXT_PROMPT` with active delegated session history
353. **Recover:** On `session.compacted`, dispatches internal prompt to restore checkpointed config
364. **Tail monitor:** Detects consecutive assistant messages with no text output; triggers recovery if recent compaction
37 
38## INTEGRATION
39 
40Registered in `create-continuation-hooks.ts` as `compactionContextInjector`.
41 
42## DISTINCTION
43 
44- **`compactionTodoPreserver`:** Preserves todos only (sibling Continuation hook)
45- **`anthropicContextWindowLimitRecovery`:** Prevents the limit preemptively (Session Tier)
46