# Upgrade Guide — vNEXT

<!-- bump: patch -->

## What Changed

### Session Resume: HTTP hooks replaced with command hooks

Claude Code HTTP hooks (`type: "http"` in settings.json) silently fail to fire as of v2.1.78. This caused `claudeSessionId` to never be populated, making session resume fall back to the unreliable mtime heuristic — cross-contaminating UUIDs across topics.

All 9 HTTP hooks replaced with command hooks running `hook-event-reporter.js`, which reads the hook payload from stdin, extracts the Claude Code session UUID, and POSTs it to `/hooks/events`. Command hooks reliably fire on every tool call.

`PostUpdateMigrator.migrateHttpHooksToCommandHooks()` automatically replaces HTTP hooks in existing agents and installs the reporter script.

### Session resume: authoritative claudeSessionId

`beforeSessionKill` and the resume heartbeat now use `session.claudeSessionId` (populated by hook events) instead of the mtime heuristic. The mtime fallback is only used when exactly one session is active (no ambiguity).

### Tests

44 new tests across 4 files, 115 total resume-related tests passing. Covers: HTTP-to-command migration, claudeSessionId bridging, migration parity, hook installation, and e2e resume flows.

## What to Tell Your User

- **Session resume is more reliable now.** Previously, killing a session and sending a new message sometimes started a fresh conversation instead of resuming. The mechanism that tracks which conversation belongs to which session has been rebuilt and is now confirmed working.

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Reliable session resume | Automatic — sessions correctly save and restore conversation context |
| HTTP to command hook migration | Automatic — existing agents get patched on next update |
