@mariozechner/pi-coding-agent 0.30.1 → 0.31.0

package/dist/core/agent-session.js

@@ -13,11 +13,12 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import { isContextOverflow, modelsAreEqual, supportsXhigh } from "@mariozechner/pi-ai";
-import { getModelsPath } from "../config.js";
+import { getAuthPath } from "../config.js";
 import { executeBash as executeBashCommand } from "./bash-executor.js";
-import { calculateContextTokens, compact, prepareCompaction, shouldCompact } from "./compaction.js";
-import { exportSessionToHtml } from "./export-html.js";
+import { calculateContextTokens, collectEntriesForBranchSummary, compact, generateBranchSummary, prepareCompaction, shouldCompact, } from "./compaction/index.js";
+import { exportSessionToHtml } from "./export-html/index.js";
 import { expandSlashCommand } from "./slash-commands.js";
+/** Internal marker for hook messages queued through the agent loop */
 // ============================================================================
 // Constants
 // ============================================================================
@@ -40,18 +41,20 @@ export class AgentSession {
     // Message queue state
     _queuedMessages = [];
     // Compaction state
-    _compactionAbortController = null;
-    _autoCompactionAbortController = null;
+    _compactionAbortController = undefined;
+    _autoCompactionAbortController = undefined;
+    // Branch summarization state
+    _branchSummaryAbortController = undefined;
     // Retry state
-    _retryAbortController = null;
+    _retryAbortController = undefined;
     _retryAttempt = 0;
-    _retryPromise = null;
-    _retryResolve = null;
+    _retryPromise = undefined;
+    _retryResolve = undefined;
     // Bash execution state
-    _bashAbortController = null;
+    _bashAbortController = undefined;
     _pendingBashMessages = [];
     // Hook system
-    _hookRunner = null;
+    _hookRunner = undefined;
     _turnIndex = 0;
     // Custom tools for session lifecycle
     _customTools = [];
@@ -64,10 +67,13 @@ export class AgentSession {
         this.settingsManager = config.settingsManager;
         this._scopedModels = config.scopedModels ?? [];
         this._fileCommands = config.fileCommands ?? [];
-        this._hookRunner = config.hookRunner ?? null;
+        this._hookRunner = config.hookRunner;
         this._customTools = config.customTools ?? [];
         this._skillsSettings = config.skillsSettings;
         this._modelRegistry = config.modelRegistry;
+        // Always subscribe to agent events for internal handling
+        // (session persistence, hooks, auto-compaction, retry logic)
+        this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
     }
     /** Model registry for API key resolution and model discovery */
     get modelRegistry() {
@@ -83,7 +89,7 @@ export class AgentSession {
         }
     }
     // Track last assistant message for auto-compaction check
-    _lastAssistantMessage = null;
+    _lastAssistantMessage = undefined;
     /** Internal handler for agent events - shared by subscribe and reconnect */
     _handleAgentEvent = async (event) => {
         // When a user message starts, check if it's from the queue and remove it BEFORE emitting
@@ -105,7 +111,18 @@ export class AgentSession {
         this._emit(event);
         // Handle session persistence
         if (event.type === "message_end") {
-            this.sessionManager.saveMessage(event.message);
+            // Check if this is a hook message
+            if (event.message.role === "hookMessage") {
+                // Persist as CustomMessageEntry
+                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+            }
+            else if (event.message.role === "user" ||
+                event.message.role === "assistant" ||
+                event.message.role === "toolResult") {
+                // Regular LLM message - persist as SessionMessageEntry
+                this.sessionManager.appendMessage(event.message);
+            }
+            // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
             // Track assistant message for auto-compaction (checked on agent_end)
             if (event.message.role === "assistant") {
                 this._lastAssistantMessage = event.message;
@@ -114,7 +131,7 @@ export class AgentSession {
         // Check auto-retry and auto-compaction after agent completes
         if (event.type === "agent_end" && this._lastAssistantMessage) {
             const msg = this._lastAssistantMessage;
-            this._lastAssistantMessage = null;
+            this._lastAssistantMessage = undefined;
             // Check for retryable errors first (overloaded, rate limit, server errors)
             if (this._isRetryableError(msg)) {
                 const didRetry = await this._handleRetryableError(msg);
@@ -139,8 +156,8 @@ export class AgentSession {
     _resolveRetry() {
         if (this._retryResolve) {
             this._retryResolve();
-            this._retryResolve = null;
-            this._retryPromise = null;
+            this._retryResolve = undefined;
+            this._retryPromise = undefined;
         }
     }
     /** Extract text content from a message */
@@ -162,7 +179,7 @@ export class AgentSession {
                 return msg;
             }
         }
-        return null;
+        return undefined;
     }
     /** Emit hook events based on agent events */
     async _emitHookEvent(event) {
@@ -201,10 +218,6 @@ export class AgentSession {
      */
     subscribe(listener) {
         this._eventListeners.push(listener);
-        // Set up agent subscription if not already done
-        if (!this._unsubscribeAgent) {
-            this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
-        }
         // Return unsubscribe function for this specific listener
         return () => {
             const index = this._eventListeners.indexOf(listener);
@@ -248,7 +261,7 @@ export class AgentSession {
     get state() {
         return this.agent.state;
     }
-    /** Current model (may be null if not yet selected) */
+    /** Current model (may be undefined if not yet selected) */
     get model() {
         return this.agent.state.model;
     }
@@ -262,7 +275,7 @@ export class AgentSession {
     }
     /** Whether auto-compaction is currently running */
     get isCompacting() {
-        return this._autoCompactionAbortController !== null || this._compactionAbortController !== null;
+        return this._autoCompactionAbortController !== undefined || this._compactionAbortController !== undefined;
     }
     /** All messages including custom types like BashExecutionMessage */
     get messages() {
@@ -272,9 +285,9 @@ export class AgentSession {
     get queueMode() {
         return this.agent.getQueueMode();
     }
-    /** Current session file path, or null if sessions are disabled */
+    /** Current session file path, or undefined if sessions are disabled */
     get sessionFile() {
-        return this.sessionManager.isPersisted() ? this.sessionManager.getSessionFile() : null;
+        return this.sessionManager.getSessionFile();
     }
     /** Current session ID */
     get sessionId() {
@@ -294,6 +307,7 @@ export class AgentSession {
     /**
      * Send a prompt to the agent.
      * - Validates model and API key before sending
+     * - Handles hook commands (registered via pi.registerCommand)
      * - Expands file-based slash commands by default
      * @throws Error if no model selected or no API key available
      */
@@ -301,28 +315,91 @@ export class AgentSession {
         // Flush any pending bash messages before the new prompt
         this._flushPendingBashMessages();
         const expandCommands = options?.expandSlashCommands ?? true;
+        // Handle hook commands first (if enabled and text is a slash command)
+        if (expandCommands && text.startsWith("/")) {
+            const handled = await this._tryExecuteHookCommand(text);
+            if (handled) {
+                // Hook command executed, no prompt to send
+                return;
+            }
+        }
         // Validate model
         if (!this.model) {
             throw new Error("No model selected.\n\n" +
-                `Use /login, set an API key environment variable, or create ${getModelsPath()}\n\n` +
+                `Use /login, set an API key environment variable, or create ${getAuthPath()}\n\n` +
                 "Then use /model to select a model.");
         }
         // Validate API key
         const apiKey = await this._modelRegistry.getApiKey(this.model);
         if (!apiKey) {
             throw new Error(`No API key found for ${this.model.provider}.\n\n` +
-                `Use /login, set an API key environment variable, or create ${getModelsPath()}`);
+                `Use /login, set an API key environment variable, or create ${getAuthPath()}`);
         }
         // Check if we need to compact before sending (catches aborted responses)
         const lastAssistant = this._findLastAssistantMessage();
         if (lastAssistant) {
             await this._checkCompaction(lastAssistant, false);
         }
-        // Expand slash commands if requested
+        // Expand file-based slash commands if requested
         const expandedText = expandCommands ? expandSlashCommand(text, [...this._fileCommands]) : text;
-        await this.agent.prompt(expandedText, options?.attachments);
+        // Build messages array (hook message if any, then user message)
+        const messages = [];
+        // Add user message
+        const userContent = [{ type: "text", text: expandedText }];
+        if (options?.images) {
+            userContent.push(...options.images);
+        }
+        messages.push({
+            role: "user",
+            content: userContent,
+            timestamp: Date.now(),
+        });
+        // Emit before_agent_start hook event
+        if (this._hookRunner) {
+            const result = await this._hookRunner.emitBeforeAgentStart(expandedText, options?.images);
+            if (result?.message) {
+                messages.push({
+                    role: "hookMessage",
+                    customType: result.message.customType,
+                    content: result.message.content,
+                    display: result.message.display,
+                    details: result.message.details,
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        await this.agent.prompt(messages);
         await this.waitForRetry();
     }
+    /**
+     * Try to execute a hook command. Returns true if command was found and executed.
+     */
+    async _tryExecuteHookCommand(text) {
+        if (!this._hookRunner)
+            return false;
+        // Parse command name and args
+        const spaceIndex = text.indexOf(" ");
+        const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+        const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+        const command = this._hookRunner.getCommand(commandName);
+        if (!command)
+            return false;
+        // Get command context from hook runner (includes session control methods)
+        const ctx = this._hookRunner.createCommandContext();
+        try {
+            await command.handler(args, ctx);
+            return true;
+        }
+        catch (err) {
+            // Emit error via hook runner
+            this._hookRunner.emitError({
+                hookPath: `command:${commandName}`,
+                event: "command",
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return true;
+        }
+    }
     /**
      * Queue a message to be sent after the current response completes.
      * Use when agent is currently streaming.
@@ -335,6 +412,40 @@ export class AgentSession {
             timestamp: Date.now(),
         });
     }
+    /**
+     * Send a hook message to the session. Creates a CustomMessageEntry.
+     *
+     * Handles three cases:
+     * - Streaming: queues message, processed when loop pulls from queue
+     * - Not streaming + triggerTurn: appends to state/session, starts new turn
+     * - Not streaming + no trigger: appends to state/session, no turn
+     *
+     * @param message Hook message with customType, content, display, details
+     * @param triggerTurn If true and not streaming, triggers a new LLM turn
+     */
+    async sendHookMessage(message, triggerTurn) {
+        const appMessage = {
+            role: "hookMessage",
+            customType: message.customType,
+            content: message.content,
+            display: message.display,
+            details: message.details,
+            timestamp: Date.now(),
+        };
+        if (this.isStreaming) {
+            // Queue for processing by agent loop
+            await this.agent.queueMessage(appMessage);
+        }
+        else if (triggerTurn) {
+            // Send as prompt - agent loop will emit message events
+            await this.agent.prompt(appMessage);
+        }
+        else {
+            // Just append to agent state and session, no turn
+            this.agent.appendMessage(appMessage);
+            this.sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
+        }
+    }
     /**
      * Clear queued messages and return them.
      * Useful for restoring to editor when user aborts.
@@ -365,22 +476,19 @@ export class AgentSession {
         await this.agent.waitForIdle();
     }
     /**
-     * Reset agent and session to start fresh.
+     * Start a new session, optionally with initial messages and parent tracking.
      * Clears all messages and starts a new session.
      * Listeners are preserved and will continue receiving events.
-     * @returns true if reset completed, false if cancelled by hook
+     * @param options - Optional initial messages and parent session path
+     * @returns true if completed, false if cancelled by hook
      */
-    async reset() {
+    async newSession(options) {
         const previousSessionFile = this.sessionFile;
-        const entries = this.sessionManager.getEntries();
-        // Emit before_new event (can be cancelled)
-        if (this._hookRunner?.hasHandlers("session")) {
+        // Emit session_before_switch event with reason "new" (can be cancelled)
+        if (this._hookRunner?.hasHandlers("session_before_switch")) {
             const result = (await this._hookRunner.emit({
-                type: "session",
-                entries,
-                sessionFile: this.sessionFile,
-                previousSessionFile: null,
-                reason: "before_new",
+                type: "session_before_switch",
+                reason: "new",
             }));
             if (result?.cancel) {
                 return false;
@@ -389,22 +497,19 @@ export class AgentSession {
         this._disconnectFromAgent();
         await this.abort();
         this.agent.reset();
-        this.sessionManager.reset();
+        this.sessionManager.newSession(options);
         this._queuedMessages = [];
         this._reconnectToAgent();
-        // Emit session event with reason "new" to hooks
+        // Emit session_switch event with reason "new" to hooks
         if (this._hookRunner) {
-            this._hookRunner.setSessionFile(this.sessionFile);
             await this._hookRunner.emit({
-                type: "session",
-                entries: [],
-                sessionFile: this.sessionFile,
-                previousSessionFile,
+                type: "session_switch",
                 reason: "new",
+                previousSessionFile,
             });
         }
         // Emit session event to custom tools
-        await this._emitToolSessionEvent("new", previousSessionFile);
+        await this.emitCustomToolSessionEvent("switch", previousSessionFile);
         return true;
     }
     // =========================================================================
@@ -421,7 +526,7 @@ export class AgentSession {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
         this.agent.setModel(model);
-        this.sessionManager.saveModelChange(model.provider, model.id);
+        this.sessionManager.appendModelChange(model.provider, model.id);
         this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
         // Re-clamp thinking level for new model's capabilities
         this.setThinkingLevel(this.thinkingLevel);
@@ -430,7 +535,7 @@ export class AgentSession {
      * Cycle to next/previous model.
      * Uses scoped models (from --models flag) if available, otherwise all available models.
      * @param direction - "forward" (default) or "backward"
-     * @returns The new model info, or null if only one model available
+     * @returns The new model info, or undefined if only one model available
      */
     async cycleModel(direction = "forward") {
         if (this._scopedModels.length > 0) {
@@ -440,7 +545,7 @@ export class AgentSession {
     }
     async _cycleScopedModel(direction) {
         if (this._scopedModels.length <= 1)
-            return null;
+            return undefined;
         const currentModel = this.model;
         let currentIndex = this._scopedModels.findIndex((sm) => modelsAreEqual(sm.model, currentModel));
         if (currentIndex === -1)
@@ -455,7 +560,7 @@ export class AgentSession {
         }
         // Apply model
         this.agent.setModel(next.model);
-        this.sessionManager.saveModelChange(next.model.provider, next.model.id);
+        this.sessionManager.appendModelChange(next.model.provider, next.model.id);
         this.settingsManager.setDefaultModelAndProvider(next.model.provider, next.model.id);
         // Apply thinking level (setThinkingLevel clamps to model capabilities)
         this.setThinkingLevel(next.thinkingLevel);
@@ -464,7 +569,7 @@ export class AgentSession {
     async _cycleAvailableModel(direction) {
         const availableModels = await this._modelRegistry.getAvailable();
         if (availableModels.length <= 1)
-            return null;
+            return undefined;
         const currentModel = this.model;
         let currentIndex = availableModels.findIndex((m) => modelsAreEqual(m, currentModel));
         if (currentIndex === -1)
@@ -477,7 +582,7 @@ export class AgentSession {
             throw new Error(`No API key for ${nextModel.provider}/${nextModel.id}`);
         }
         this.agent.setModel(nextModel);
-        this.sessionManager.saveModelChange(nextModel.provider, nextModel.id);
+        this.sessionManager.appendModelChange(nextModel.provider, nextModel.id);
         this.settingsManager.setDefaultModelAndProvider(nextModel.provider, nextModel.id);
         // Re-clamp thinking level for new model's capabilities
         this.setThinkingLevel(this.thinkingLevel);
@@ -506,16 +611,16 @@ export class AgentSession {
             effectiveLevel = "high";
         }
         this.agent.setThinkingLevel(effectiveLevel);
-        this.sessionManager.saveThinkingLevelChange(effectiveLevel);
+        this.sessionManager.appendThinkingLevelChange(effectiveLevel);
         this.settingsManager.setDefaultThinkingLevel(effectiveLevel);
     }
     /**
      * Cycle to next thinking level.
-     * @returns New level, or null if model doesn't support thinking
+     * @returns New level, or undefined if model doesn't support thinking
      */
     cycleThinkingLevel() {
         if (!this.supportsThinking())
-            return null;
+            return undefined;
         const levels = this.getAvailableThinkingLevels();
         const currentIndex = levels.indexOf(this.thinkingLevel);
         const nextIndex = (currentIndex + 1) % levels.length;
@@ -572,76 +677,79 @@ export class AgentSession {
             if (!apiKey) {
                 throw new Error(`No API key for ${this.model.provider}`);
             }
-            const entries = this.sessionManager.getEntries();
+            const pathEntries = this.sessionManager.getBranch();
             const settings = this.settingsManager.getCompactionSettings();
-            const preparation = prepareCompaction(entries, settings);
+            const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
-                throw new Error("Already compacted");
-            }
-            // Find previous compaction summary if any
-            let previousSummary;
-            for (let i = entries.length - 1; i >= 0; i--) {
-                if (entries[i].type === "compaction") {
-                    previousSummary = entries[i].summary;
-                    break;
+                // Check why we can't compact
+                const lastEntry = pathEntries[pathEntries.length - 1];
+                if (lastEntry?.type === "compaction") {
+                    throw new Error("Already compacted");
                 }
+                throw new Error("Nothing to compact (session too small)");
             }
-            let compactionEntry;
+            let hookCompaction;
             let fromHook = false;
-            if (this._hookRunner?.hasHandlers("session")) {
+            if (this._hookRunner?.hasHandlers("session_before_compact")) {
                 const result = (await this._hookRunner.emit({
-                    type: "session",
-                    entries,
-                    sessionFile: this.sessionFile,
-                    previousSessionFile: null,
-                    reason: "before_compact",
-                    cutPoint: preparation.cutPoint,
-                    previousSummary,
-                    messagesToSummarize: [...preparation.messagesToSummarize],
-                    messagesToKeep: [...preparation.messagesToKeep],
-                    tokensBefore: preparation.tokensBefore,
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
                     customInstructions,
-                    model: this.model,
-                    resolveApiKey: async (m) => (await this._modelRegistry.getApiKey(m)) ?? undefined,
                     signal: this._compactionAbortController.signal,
                 }));
                 if (result?.cancel) {
                     throw new Error("Compaction cancelled");
                 }
-                if (result?.compactionEntry) {
-                    compactionEntry = result.compactionEntry;
+                if (result?.compaction) {
+                    hookCompaction = result.compaction;
                     fromHook = true;
                 }
             }
-            if (!compactionEntry) {
-                compactionEntry = await compact(entries, this.model, settings, apiKey, this._compactionAbortController.signal, customInstructions);
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let details;
+            if (hookCompaction) {
+                // Hook provided compaction content
+                summary = hookCompaction.summary;
+                firstKeptEntryId = hookCompaction.firstKeptEntryId;
+                tokensBefore = hookCompaction.tokensBefore;
+                details = hookCompaction.details;
+            }
+            else {
+                // Generate compaction result
+                const result = await compact(preparation, this.model, apiKey, customInstructions, this._compactionAbortController.signal);
+                summary = result.summary;
+                firstKeptEntryId = result.firstKeptEntryId;
+                tokensBefore = result.tokensBefore;
+                details = result.details;
             }
             if (this._compactionAbortController.signal.aborted) {
                 throw new Error("Compaction cancelled");
             }
-            this.sessionManager.saveCompaction(compactionEntry);
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook);
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
             this.agent.replaceMessages(sessionContext.messages);
-            if (this._hookRunner) {
+            // Get the saved compaction entry for the hook
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (this._hookRunner && savedCompactionEntry) {
                 await this._hookRunner.emit({
-                    type: "session",
-                    entries: newEntries,
-                    sessionFile: this.sessionFile,
-                    previousSessionFile: null,
-                    reason: "compact",
-                    compactionEntry,
-                    tokensBefore: compactionEntry.tokensBefore,
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
                     fromHook,
                 });
             }
             return {
-                tokensBefore: compactionEntry.tokensBefore,
-                summary: compactionEntry.summary,
+                summary,
+                firstKeptEntryId,
+                tokensBefore,
+                details,
             };
         }
         finally {
-            this._compactionAbortController = null;
+            this._compactionAbortController = undefined;
             this._reconnectToAgent();
         }
     }
@@ -652,6 +760,12 @@ export class AgentSession {
         this._compactionAbortController?.abort();
         this._autoCompactionAbortController?.abort();
     }
+    /**
+     * Cancel in-progress branch summarization.
+     */
+    abortBranchSummary() {
+        this._branchSummaryAbortController?.abort();
+    }
     /**
      * Check if compaction is needed and run it.
      * Called after agent_end and before prompt submission.
@@ -700,82 +814,80 @@ export class AgentSession {
         this._autoCompactionAbortController = new AbortController();
         try {
             if (!this.model) {
-                this._emit({ type: "auto_compaction_end", result: null, aborted: false, willRetry: false });
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
                 return;
             }
             const apiKey = await this._modelRegistry.getApiKey(this.model);
             if (!apiKey) {
-                this._emit({ type: "auto_compaction_end", result: null, aborted: false, willRetry: false });
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
                 return;
             }
-            const entries = this.sessionManager.getEntries();
-            const preparation = prepareCompaction(entries, settings);
+            const pathEntries = this.sessionManager.getBranch();
+            const preparation = prepareCompaction(pathEntries, settings);
             if (!preparation) {
-                this._emit({ type: "auto_compaction_end", result: null, aborted: false, willRetry: false });
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
                 return;
             }
-            // Find previous compaction summary if any
-            let previousSummary;
-            for (let i = entries.length - 1; i >= 0; i--) {
-                if (entries[i].type === "compaction") {
-                    previousSummary = entries[i].summary;
-                    break;
-                }
-            }
-            let compactionEntry;
+            let hookCompaction;
             let fromHook = false;
-            if (this._hookRunner?.hasHandlers("session")) {
+            if (this._hookRunner?.hasHandlers("session_before_compact")) {
                 const hookResult = (await this._hookRunner.emit({
-                    type: "session",
-                    entries,
-                    sessionFile: this.sessionFile,
-                    previousSessionFile: null,
-                    reason: "before_compact",
-                    cutPoint: preparation.cutPoint,
-                    previousSummary,
-                    messagesToSummarize: [...preparation.messagesToSummarize],
-                    messagesToKeep: [...preparation.messagesToKeep],
-                    tokensBefore: preparation.tokensBefore,
+                    type: "session_before_compact",
+                    preparation,
+                    branchEntries: pathEntries,
                     customInstructions: undefined,
-                    model: this.model,
-                    resolveApiKey: async (m) => (await this._modelRegistry.getApiKey(m)) ?? undefined,
                     signal: this._autoCompactionAbortController.signal,
                 }));
                 if (hookResult?.cancel) {
-                    this._emit({ type: "auto_compaction_end", result: null, aborted: true, willRetry: false });
+                    this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
                     return;
                 }
-                if (hookResult?.compactionEntry) {
-                    compactionEntry = hookResult.compactionEntry;
+                if (hookResult?.compaction) {
+                    hookCompaction = hookResult.compaction;
                     fromHook = true;
                 }
             }
-            if (!compactionEntry) {
-                compactionEntry = await compact(entries, this.model, settings, apiKey, this._autoCompactionAbortController.signal);
+            let summary;
+            let firstKeptEntryId;
+            let tokensBefore;
+            let details;
+            if (hookCompaction) {
+                // Hook provided compaction content
+                summary = hookCompaction.summary;
+                firstKeptEntryId = hookCompaction.firstKeptEntryId;
+                tokensBefore = hookCompaction.tokensBefore;
+                details = hookCompaction.details;
+            }
+            else {
+                // Generate compaction result
+                const compactResult = await compact(preparation, this.model, apiKey, undefined, this._autoCompactionAbortController.signal);
+                summary = compactResult.summary;
+                firstKeptEntryId = compactResult.firstKeptEntryId;
+                tokensBefore = compactResult.tokensBefore;
+                details = compactResult.details;
             }
             if (this._autoCompactionAbortController.signal.aborted) {
-                this._emit({ type: "auto_compaction_end", result: null, aborted: true, willRetry: false });
+                this._emit({ type: "auto_compaction_end", result: undefined, aborted: true, willRetry: false });
                 return;
             }
-            this.sessionManager.saveCompaction(compactionEntry);
+            this.sessionManager.appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook);
             const newEntries = this.sessionManager.getEntries();
             const sessionContext = this.sessionManager.buildSessionContext();
             this.agent.replaceMessages(sessionContext.messages);
-            if (this._hookRunner) {
+            // Get the saved compaction entry for the hook
+            const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary);
+            if (this._hookRunner && savedCompactionEntry) {
                 await this._hookRunner.emit({
-                    type: "session",
-                    entries: newEntries,
-                    sessionFile: this.sessionFile,
-                    previousSessionFile: null,
-                    reason: "compact",
-                    compactionEntry,
-                    tokensBefore: compactionEntry.tokensBefore,
+                    type: "session_compact",
+                    compactionEntry: savedCompactionEntry,
                     fromHook,
                 });
             }
             const result = {
-                tokensBefore: compactionEntry.tokensBefore,
-                summary: compactionEntry.summary,
+                summary,
+                firstKeptEntryId,
+                tokensBefore,
+                details,
             };
             this._emit({ type: "auto_compaction_end", result, aborted: false, willRetry });
             if (willRetry) {
@@ -790,13 +902,13 @@ export class AgentSession {
             }
         }
         catch (error) {
-            this._emit({ type: "auto_compaction_end", result: null, aborted: false, willRetry: false });
+            this._emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
             if (reason === "overflow") {
                 throw new Error(`Context overflow: ${error instanceof Error ? error.message : "compaction failed"}. Your input may be too large for the context window.`);
             }
         }
         finally {
-            this._autoCompactionAbortController = null;
+            this._autoCompactionAbortController = undefined;
         }
     }
     /**
@@ -876,7 +988,7 @@ export class AgentSession {
             // Aborted during sleep - emit end event so UI can clean up
             const attempt = this._retryAttempt;
             this._retryAttempt = 0;
-            this._retryAbortController = null;
+            this._retryAbortController = undefined;
             this._emit({
                 type: "auto_retry_end",
                 success: false,
@@ -886,7 +998,7 @@ export class AgentSession {
             this._resolveRetry();
             return false;
         }
-        this._retryAbortController = null;
+        this._retryAbortController = undefined;
         // Retry via continue() - use setTimeout to break out of event handler chain
         setTimeout(() => {
             this.agent.continue().catch(() => {
@@ -930,7 +1042,7 @@ export class AgentSession {
     }
     /** Whether auto-retry is currently in progress */
     get isRetrying() {
-        return this._retryPromise !== null;
+        return this._retryPromise !== undefined;
     }
     /** Whether auto-retry is enabled */
     get autoRetryEnabled() {
@@ -978,12 +1090,12 @@ export class AgentSession {
                 // Add to agent state immediately
                 this.agent.appendMessage(bashMessage);
                 // Save to session
-                this.sessionManager.saveMessage(bashMessage);
+                this.sessionManager.appendMessage(bashMessage);
             }
             return result;
         }
         finally {
-            this._bashAbortController = null;
+            this._bashAbortController = undefined;
         }
     }
     /**
@@ -994,7 +1106,7 @@ export class AgentSession {
     }
     /** Whether a bash command is currently running */
     get isBashRunning() {
-        return this._bashAbortController !== null;
+        return this._bashAbortController !== undefined;
     }
     /** Whether there are pending bash messages waiting to be flushed */
     get hasPendingBashMessages() {
@@ -1011,7 +1123,7 @@ export class AgentSession {
             // Add to agent state
             this.agent.appendMessage(bashMessage);
             // Save to session
-            this.sessionManager.saveMessage(bashMessage);
+            this.sessionManager.appendMessage(bashMessage);
         }
         this._pendingBashMessages = [];
     }
@@ -1025,16 +1137,13 @@ export class AgentSession {
      * @returns true if switch completed, false if cancelled by hook
      */
     async switchSession(sessionPath) {
-        const previousSessionFile = this.sessionFile;
-        const oldEntries = this.sessionManager.getEntries();
-        // Emit before_switch event (can be cancelled)
-        if (this._hookRunner?.hasHandlers("session")) {
+        const previousSessionFile = this.sessionManager.getSessionFile();
+        // Emit session_before_switch event (can be cancelled)
+        if (this._hookRunner?.hasHandlers("session_before_switch")) {
             const result = (await this._hookRunner.emit({
-                type: "session",
-                entries: oldEntries,
-                sessionFile: this.sessionFile,
-                previousSessionFile: null,
-                reason: "before_switch",
+                type: "session_before_switch",
+                reason: "resume",
+                targetSessionFile: sessionPath,
             }));
             if (result?.cancel) {
                 return false;
@@ -1046,21 +1155,17 @@ export class AgentSession {
         // Set new session
         this.sessionManager.setSessionFile(sessionPath);
         // Reload messages
-        const entries = this.sessionManager.getEntries();
         const sessionContext = this.sessionManager.buildSessionContext();
-        // Emit session event to hooks
+        // Emit session_switch event to hooks
         if (this._hookRunner) {
-            this._hookRunner.setSessionFile(sessionPath);
             await this._hookRunner.emit({
-                type: "session",
-                entries,
-                sessionFile: sessionPath,
+                type: "session_switch",
+                reason: "resume",
                 previousSessionFile,
-                reason: "switch",
             });
         }
         // Emit session event to custom tools
-        await this._emitToolSessionEvent("switch", previousSessionFile);
+        await this.emitCustomToolSessionEvent("switch", previousSessionFile);
         this.agent.replaceMessages(sessionContext.messages);
         // Restore model if saved
         if (sessionContext.model) {
@@ -1078,81 +1183,215 @@ export class AgentSession {
         return true;
     }
     /**
-     * Create a branch from a specific entry index.
+     * Create a branch from a specific entry.
      * Emits before_branch/branch session events to hooks.
      *
-     * @param entryIndex Index into session entries to branch from
+     * @param entryId ID of the entry to branch from
      * @returns Object with:
      *   - selectedText: The text of the selected user message (for editor pre-fill)
      *   - cancelled: True if a hook cancelled the branch
      */
-    async branch(entryIndex) {
+    async branch(entryId) {
         const previousSessionFile = this.sessionFile;
-        const entries = this.sessionManager.getEntries();
-        const selectedEntry = entries[entryIndex];
+        const selectedEntry = this.sessionManager.getEntry(entryId);
         if (!selectedEntry || selectedEntry.type !== "message" || selectedEntry.message.role !== "user") {
-            throw new Error("Invalid entry index for branching");
+            throw new Error("Invalid entry ID for branching");
         }
         const selectedText = this._extractUserMessageText(selectedEntry.message.content);
         let skipConversationRestore = false;
-        // Emit before_branch event (can be cancelled)
-        if (this._hookRunner?.hasHandlers("session")) {
+        // Emit session_before_branch event (can be cancelled)
+        if (this._hookRunner?.hasHandlers("session_before_branch")) {
             const result = (await this._hookRunner.emit({
-                type: "session",
-                entries,
-                sessionFile: this.sessionFile,
-                previousSessionFile: null,
-                reason: "before_branch",
-                targetTurnIndex: entryIndex,
+                type: "session_before_branch",
+                entryId,
             }));
             if (result?.cancel) {
                 return { selectedText, cancelled: true };
             }
             skipConversationRestore = result?.skipConversationRestore ?? false;
         }
-        // Create branched session (returns null in --no-session mode)
-        const newSessionFile = this.sessionManager.createBranchedSessionFromEntries(entries, entryIndex);
-        // Update session file if we have one (file-based mode)
-        if (newSessionFile !== null) {
-            this.sessionManager.setSessionFile(newSessionFile);
+        if (!selectedEntry.parentId) {
+            this.sessionManager.newSession();
+        }
+        else {
+            this.sessionManager.createBranchedSession(selectedEntry.parentId);
         }
         // Reload messages from entries (works for both file and in-memory mode)
-        const newEntries = this.sessionManager.getEntries();
         const sessionContext = this.sessionManager.buildSessionContext();
-        // Emit branch event to hooks (after branch completes)
+        // Emit session_branch event to hooks (after branch completes)
         if (this._hookRunner) {
-            this._hookRunner.setSessionFile(newSessionFile);
             await this._hookRunner.emit({
-                type: "session",
-                entries: newEntries,
-                sessionFile: newSessionFile,
+                type: "session_branch",
                 previousSessionFile,
-                reason: "branch",
-                targetTurnIndex: entryIndex,
             });
         }
         // Emit session event to custom tools (with reason "branch")
-        await this._emitToolSessionEvent("branch", previousSessionFile);
+        await this.emitCustomToolSessionEvent("branch", previousSessionFile);
         if (!skipConversationRestore) {
             this.agent.replaceMessages(sessionContext.messages);
         }
         return { selectedText, cancelled: false };
     }
+    // =========================================================================
+    // Tree Navigation
+    // =========================================================================
+    /**
+     * Navigate to a different node in the session tree.
+     * Unlike branch() which creates a new session file, this stays in the same file.
+     *
+     * @param targetId The entry ID to navigate to
+     * @param options.summarize Whether user wants to summarize abandoned branch
+     * @param options.customInstructions Custom instructions for summarizer
+     * @returns Result with editorText (if user message) and cancelled status
+     */
+    async navigateTree(targetId, options = {}) {
+        const oldLeafId = this.sessionManager.getLeafId();
+        // No-op if already at target
+        if (targetId === oldLeafId) {
+            return { cancelled: false };
+        }
+        // Model required for summarization
+        if (options.summarize && !this.model) {
+            throw new Error("No model available for summarization");
+        }
+        const targetEntry = this.sessionManager.getEntry(targetId);
+        if (!targetEntry) {
+            throw new Error(`Entry ${targetId} not found`);
+        }
+        // Collect entries to summarize (from old leaf to common ancestor)
+        const { entries: entriesToSummarize, commonAncestorId } = collectEntriesForBranchSummary(this.sessionManager, oldLeafId, targetId);
+        // Prepare event data
+        const preparation = {
+            targetId,
+            oldLeafId,
+            commonAncestorId,
+            entriesToSummarize,
+            userWantsSummary: options.summarize ?? false,
+        };
+        // Set up abort controller for summarization
+        this._branchSummaryAbortController = new AbortController();
+        let hookSummary;
+        let fromHook = false;
+        // Emit session_before_tree event
+        if (this._hookRunner?.hasHandlers("session_before_tree")) {
+            const result = (await this._hookRunner.emit({
+                type: "session_before_tree",
+                preparation,
+                signal: this._branchSummaryAbortController.signal,
+            }));
+            if (result?.cancel) {
+                return { cancelled: true };
+            }
+            if (result?.summary && options.summarize) {
+                hookSummary = result.summary;
+                fromHook = true;
+            }
+        }
+        // Run default summarizer if needed
+        let summaryText;
+        let summaryDetails;
+        if (options.summarize && entriesToSummarize.length > 0 && !hookSummary) {
+            const model = this.model;
+            const apiKey = await this._modelRegistry.getApiKey(model);
+            if (!apiKey) {
+                throw new Error(`No API key for ${model.provider}`);
+            }
+            const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
+            const result = await generateBranchSummary(entriesToSummarize, {
+                model,
+                apiKey,
+                signal: this._branchSummaryAbortController.signal,
+                customInstructions: options.customInstructions,
+                reserveTokens: branchSummarySettings.reserveTokens,
+            });
+            this._branchSummaryAbortController = undefined;
+            if (result.aborted) {
+                return { cancelled: true, aborted: true };
+            }
+            if (result.error) {
+                throw new Error(result.error);
+            }
+            summaryText = result.summary;
+            summaryDetails = {
+                readFiles: result.readFiles || [],
+                modifiedFiles: result.modifiedFiles || [],
+            };
+        }
+        else if (hookSummary) {
+            summaryText = hookSummary.summary;
+            summaryDetails = hookSummary.details;
+        }
+        // Determine the new leaf position based on target type
+        let newLeafId;
+        let editorText;
+        if (targetEntry.type === "message" && targetEntry.message.role === "user") {
+            // User message: leaf = parent (null if root), text goes to editor
+            newLeafId = targetEntry.parentId;
+            editorText = this._extractUserMessageText(targetEntry.message.content);
+        }
+        else if (targetEntry.type === "custom_message") {
+            // Custom message: leaf = parent (null if root), text goes to editor
+            newLeafId = targetEntry.parentId;
+            editorText =
+                typeof targetEntry.content === "string"
+                    ? targetEntry.content
+                    : targetEntry.content
+                        .filter((c) => c.type === "text")
+                        .map((c) => c.text)
+                        .join("");
+        }
+        else {
+            // Non-user message: leaf = selected node
+            newLeafId = targetId;
+        }
+        // Switch leaf (with or without summary)
+        // Summary is attached at the navigation target position (newLeafId), not the old branch
+        let summaryEntry;
+        if (summaryText) {
+            // Create summary at target position (can be null for root)
+            const summaryId = this.sessionManager.branchWithSummary(newLeafId, summaryText, summaryDetails, fromHook);
+            summaryEntry = this.sessionManager.getEntry(summaryId);
+        }
+        else if (newLeafId === null) {
+            // No summary, navigating to root - reset leaf
+            this.sessionManager.resetLeaf();
+        }
+        else {
+            // No summary, navigating to non-root
+            this.sessionManager.branch(newLeafId);
+        }
+        // Update agent state
+        const sessionContext = this.sessionManager.buildSessionContext();
+        this.agent.replaceMessages(sessionContext.messages);
+        // Emit session_tree event
+        if (this._hookRunner) {
+            await this._hookRunner.emit({
+                type: "session_tree",
+                newLeafId: this.sessionManager.getLeafId(),
+                oldLeafId,
+                summaryEntry,
+                fromHook: summaryText ? fromHook : undefined,
+            });
+        }
+        // Emit to custom tools
+        await this.emitCustomToolSessionEvent("tree", this.sessionFile);
+        this._branchSummaryAbortController = undefined;
+        return { editorText, cancelled: false, summaryEntry };
+    }
     /**
      * Get all user messages from session for branch selector.
      */
     getUserMessagesForBranching() {
         const entries = this.sessionManager.getEntries();
         const result = [];
-        for (let i = 0; i < entries.length; i++) {
-            const entry = entries[i];
+        for (const entry of entries) {
             if (entry.type !== "message")
                 continue;
             if (entry.message.role !== "user")
                 continue;
             const text = this._extractUserMessageText(entry.message.content);
             if (text) {
-                result.push({ entryIndex: i, text });
+                result.push({ entryId: entry.id, text });
             }
         }
         return result;
@@ -1226,22 +1465,30 @@ export class AgentSession {
     /**
      * Get text content of last assistant message.
      * Useful for /copy command.
-     * @returns Text content, or null if no assistant message exists
+     * @returns Text content, or undefined if no assistant message exists
      */
     getLastAssistantText() {
         const lastAssistant = this.messages
             .slice()
             .reverse()
-            .find((m) => m.role === "assistant");
+            .find((m) => {
+            if (m.role !== "assistant")
+                return false;
+            const msg = m;
+            // Skip aborted messages with no content
+            if (msg.stopReason === "aborted" && msg.content.length === 0)
+                return false;
+            return true;
+        });
         if (!lastAssistant)
-            return null;
+            return undefined;
         let text = "";
         for (const content of lastAssistant.content) {
             if (content.type === "text") {
                 text += content.text;
             }
         }
-        return text.trim() || null;
+        return text.trim() || undefined;
     }
     // =========================================================================
     // Hook System
@@ -1266,19 +1513,26 @@ export class AgentSession {
     }
     /**
      * Emit session event to all custom tools.
-     * Called on session switch, branch, and clear.
+     * Called on session switch, branch, tree navigation, and shutdown.
      */
-    async _emitToolSessionEvent(reason, previousSessionFile) {
-        const event = {
-            entries: this.sessionManager.getEntries(),
-            sessionFile: this.sessionFile,
-            previousSessionFile,
-            reason,
+    async emitCustomToolSessionEvent(reason, previousSessionFile) {
+        if (!this._customTools)
+            return;
+        const event = { reason, previousSessionFile };
+        const ctx = {
+            sessionManager: this.sessionManager,
+            modelRegistry: this._modelRegistry,
+            model: this.agent.state.model,
+            isIdle: () => !this.isStreaming,
+            hasQueuedMessages: () => this.queuedMessageCount > 0,
+            abort: () => {
+                this.abort();
+            },
         };
         for (const { tool } of this._customTools) {
             if (tool.onSession) {
                 try {
-                    await tool.onSession(event);
+                    await tool.onSession(event, ctx);
                 }
                 catch (_err) {
                     // Silently ignore tool errors during session events