@mariozechner/pi-coding-agent 0.30.2 → 0.31.1

package/dist/core/hooks/tool-wrapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-wrapper.js","sourceRoot":"","sources":["../../../src/core/hooks/tool-wrapper.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAI,IAAuB,EAAE,UAAsB,EAAqB;IACxG,OAAO;QACN,GAAG,IAAI;QACP,OAAO,EAAE,KAAK,EACb,UAAkB,EAClB,MAA+B,EAC/B,MAAoB,EACpB,QAAqC,EACpC,EAAE,CAAC;YACJ,mDAAmD;YACnD,yDAAyD;YACzD,IAAI,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;gBACzC,IAAI,CAAC;oBACJ,MAAM,UAAU,GAAG,CAAC,MAAM,UAAU,CAAC,YAAY,CAAC;wBACjD,IAAI,EAAE,WAAW;wBACjB,QAAQ,EAAE,IAAI,CAAC,IAAI;wBACnB,UAAU;wBACV,KAAK,EAAE,MAAM;qBACb,CAAC,CAAoC,CAAC;oBAEvC,IAAI,UAAU,EAAE,KAAK,EAAE,CAAC;wBACvB,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,IAAI,sCAAsC,CAAC;wBAC3E,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;oBACzB,CAAC;gBACF,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACd,+CAA+C;oBAC/C,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;wBAC1B,MAAM,GAAG,CAAC;oBACX,CAAC;oBACD,MAAM,IAAI,KAAK,CAAC,oCAAoC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACpE,CAAC;YACF,CAAC;YAED,sEAAsE;YACtE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;YAExE,uDAAuD;YACvD,IAAI,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC;gBAC3C,MAAM,YAAY,GAAG,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC;oBAC3C,IAAI,EAAE,aAAa;oBACnB,QAAQ,EAAE,IAAI,CAAC,IAAI;oBACnB,UAAU;oBACV,KAAK,EAAE,MAAM;oBACb,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,OAAO,EAAE,KAAK;iBACd,CAAC,CAAsC,CAAC;gBAEzC,6BAA6B;gBAC7B,IAAI,YAAY,EAAE,CAAC;oBAClB,OAAO;wBACN,OAAO,EAAE,YAAY,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO;wBAC/C,OAAO,EAAE,CAAC,YAAY,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAM;qBACtD,CAAC;gBACH,CAAC;YACF,CAAC;YAED,OAAO,MAAM,CAAC;QAAA,CACd;KACD,CAAC;AAAA,CACF;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAI,KAA0B,EAAE,UAAsB,EAAuB;IAC9G,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;AAAA,CAChE","sourcesContent":["/**\n * Tool wrapper - wraps tools with hook callbacks for interception.\n */\n\nimport type { AgentTool, AgentToolUpdateCallback } from \"@mariozechner/pi-ai\";\nimport type { HookRunner } from \"./runner.js\";\nimport type { ToolCallEventResult, ToolResultEventResult } from \"./types.js\";\n\n/**\n * Wrap a tool with hook callbacks.\n * - Emits tool_call event before execution (can block)\n * - Emits tool_result event after execution (can modify result)\n * - Forwards onUpdate callback to wrapped tool for progress streaming\n */\nexport function wrapToolWithHooks<T>(tool: AgentTool<any, T>, hookRunner: HookRunner): AgentTool<any, T> {\n\treturn {\n\t\t...tool,\n\t\texecute: async (\n\t\t\ttoolCallId: string,\n\t\t\tparams: Record<string, unknown>,\n\t\t\tsignal?: AbortSignal,\n\t\t\tonUpdate?: AgentToolUpdateCallback<T>,\n\t\t) => {\n\t\t\t// Emit tool_call event - hooks can block execution\n\t\t\t// If hook errors/times out, block by default (fail-safe)\n\t\t\tif (hookRunner.hasHandlers(\"tool_call\")) {\n\t\t\t\ttry {\n\t\t\t\t\tconst callResult = (await hookRunner.emitToolCall({\n\t\t\t\t\t\ttype: \"tool_call\",\n\t\t\t\t\t\ttoolName: tool.name,\n\t\t\t\t\t\ttoolCallId,\n\t\t\t\t\t\tinput: params,\n\t\t\t\t\t})) as ToolCallEventResult | undefined;\n\n\t\t\t\t\tif (callResult?.block) {\n\t\t\t\t\t\tconst reason = callResult.reason || \"Tool execution was blocked by a hook\";\n\t\t\t\t\t\tthrow new Error(reason);\n\t\t\t\t\t}\n\t\t\t\t} catch (err) {\n\t\t\t\t\t// Hook error or block - throw to mark as error\n\t\t\t\t\tif (err instanceof Error) {\n\t\t\t\t\t\tthrow err;\n\t\t\t\t\t}\n\t\t\t\t\tthrow new Error(`Hook failed, blocking execution: ${String(err)}`);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Execute the actual tool, forwarding onUpdate for progress streaming\n\t\t\tconst result = await tool.execute(toolCallId, params, signal, onUpdate);\n\n\t\t\t// Emit tool_result event - hooks can modify the result\n\t\t\tif (hookRunner.hasHandlers(\"tool_result\")) {\n\t\t\t\tconst resultResult = (await hookRunner.emit({\n\t\t\t\t\ttype: \"tool_result\",\n\t\t\t\t\ttoolName: tool.name,\n\t\t\t\t\ttoolCallId,\n\t\t\t\t\tinput: params,\n\t\t\t\t\tcontent: result.content,\n\t\t\t\t\tdetails: result.details,\n\t\t\t\t\tisError: false,\n\t\t\t\t})) as ToolResultEventResult | undefined;\n\n\t\t\t\t// Apply modifications if any\n\t\t\t\tif (resultResult) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tcontent: resultResult.content ?? result.content,\n\t\t\t\t\t\tdetails: (resultResult.details ?? result.details) as T,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}\n\n\t\t\treturn result;\n\t\t},\n\t};\n}\n\n/**\n * Wrap all tools with hook callbacks.\n */\nexport function wrapToolsWithHooks<T>(tools: AgentTool<any, T>[], hookRunner: HookRunner): AgentTool<any, T>[] {\n\treturn tools.map((tool) => wrapToolWithHooks(tool, hookRunner));\n}\n"]}
+{"version":3,"file":"tool-wrapper.js","sourceRoot":"","sources":["../../../src/core/hooks/tool-wrapper.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Tool wrapper - wraps tools with hook callbacks for interception.\n */\n\nimport type { AgentTool, AgentToolUpdateCallback } from \"@mariozechner/pi-agent-core\";\nimport type { HookRunner } from \"./runner.js\";\nimport type { ToolCallEventResult, ToolResultEventResult } from \"./types.js\";\n\n/**\n * Wrap a tool with hook callbacks.\n * - Emits tool_call event before execution (can block)\n * - Emits tool_result event after execution (can modify result)\n * - Forwards onUpdate callback to wrapped tool for progress streaming\n */\nexport function wrapToolWithHooks<T>(tool: AgentTool<any, T>, hookRunner: HookRunner): AgentTool<any, T> {\n\treturn {\n\t\t...tool,\n\t\texecute: async (\n\t\t\ttoolCallId: string,\n\t\t\tparams: Record<string, unknown>,\n\t\t\tsignal?: AbortSignal,\n\t\t\tonUpdate?: AgentToolUpdateCallback<T>,\n\t\t) => {\n\t\t\t// Emit tool_call event - hooks can block execution\n\t\t\t// If hook errors/times out, block by default (fail-safe)\n\t\t\tif (hookRunner.hasHandlers(\"tool_call\")) {\n\t\t\t\ttry {\n\t\t\t\t\tconst callResult = (await hookRunner.emitToolCall({\n\t\t\t\t\t\ttype: \"tool_call\",\n\t\t\t\t\t\ttoolName: tool.name,\n\t\t\t\t\t\ttoolCallId,\n\t\t\t\t\t\tinput: params,\n\t\t\t\t\t})) as ToolCallEventResult | undefined;\n\n\t\t\t\t\tif (callResult?.block) {\n\t\t\t\t\t\tconst reason = callResult.reason || \"Tool execution was blocked by a hook\";\n\t\t\t\t\t\tthrow new Error(reason);\n\t\t\t\t\t}\n\t\t\t\t} catch (err) {\n\t\t\t\t\t// Hook error or block - throw to mark as error\n\t\t\t\t\tif (err instanceof Error) {\n\t\t\t\t\t\tthrow err;\n\t\t\t\t\t}\n\t\t\t\t\tthrow new Error(`Hook failed, blocking execution: ${String(err)}`);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Execute the actual tool, forwarding onUpdate for progress streaming\n\t\t\ttry {\n\t\t\t\tconst result = await tool.execute(toolCallId, params, signal, onUpdate);\n\n\t\t\t\t// Emit tool_result event - hooks can modify the result\n\t\t\t\tif (hookRunner.hasHandlers(\"tool_result\")) {\n\t\t\t\t\tconst resultResult = (await hookRunner.emit({\n\t\t\t\t\t\ttype: \"tool_result\",\n\t\t\t\t\t\ttoolName: tool.name,\n\t\t\t\t\t\ttoolCallId,\n\t\t\t\t\t\tinput: params,\n\t\t\t\t\t\tcontent: result.content,\n\t\t\t\t\t\tdetails: result.details,\n\t\t\t\t\t\tisError: false,\n\t\t\t\t\t})) as ToolResultEventResult | undefined;\n\n\t\t\t\t\t// Apply modifications if any\n\t\t\t\t\tif (resultResult) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tcontent: resultResult.content ?? result.content,\n\t\t\t\t\t\t\tdetails: (resultResult.details ?? result.details) as T,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\treturn result;\n\t\t\t} catch (err) {\n\t\t\t\t// Emit tool_result event for errors so hooks can observe failures\n\t\t\t\tif (hookRunner.hasHandlers(\"tool_result\")) {\n\t\t\t\t\tawait hookRunner.emit({\n\t\t\t\t\t\ttype: \"tool_result\",\n\t\t\t\t\t\ttoolName: tool.name,\n\t\t\t\t\t\ttoolCallId,\n\t\t\t\t\t\tinput: params,\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: err instanceof Error ? err.message : String(err) }],\n\t\t\t\t\t\tdetails: undefined,\n\t\t\t\t\t\tisError: true,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tthrow err; // Re-throw original error for agent-loop\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Wrap all tools with hook callbacks.\n */\nexport function wrapToolsWithHooks<T>(tools: AgentTool<any, T>[], hookRunner: HookRunner): AgentTool<any, T>[] {\n\treturn tools.map((tool) => wrapToolWithHooks(tool, hookRunner));\n}\n"]}

package/dist/core/hooks/types.d.ts

@@ -4,27 +4,18 @@
  * Hooks are TypeScript modules that can subscribe to agent lifecycle events
  * and interact with the user via UI primitives.
  */
-import type { AppMessage, Attachment } from "@mariozechner/pi-agent-core";
-import type { ImageContent, Model, TextContent, ToolResultMessage } from "@mariozechner/pi-ai";
-import type { CutPointResult } from "../compaction.js";
-import type { CompactionEntry, SessionEntry } from "../session-manager.js";
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import type { ImageContent, Message, Model, TextContent, ToolResultMessage } from "@mariozechner/pi-ai";
+import type { Component, TUI } from "@mariozechner/pi-tui";
+import type { Theme } from "../../modes/interactive/theme/theme.js";
+import type { CompactionPreparation, CompactionResult } from "../compaction/index.js";
+import type { ExecOptions, ExecResult } from "../exec.js";
+import type { HookMessage } from "../messages.js";
+import type { ModelRegistry } from "../model-registry.js";
+import type { BranchSummaryEntry, CompactionEntry, ReadonlySessionManager, SessionEntry, SessionManager } from "../session-manager.js";
+import type { EditToolDetails } from "../tools/edit.js";
 import type { BashToolDetails, FindToolDetails, GrepToolDetails, LsToolDetails, ReadToolDetails } from "../tools/index.js";
-/**
- * Result of executing a command via ctx.exec()
- */
-export interface ExecResult {
-    stdout: string;
-    stderr: string;
-    code: number;
-    /** True if the process was killed due to signal or timeout */
-    killed?: boolean;
-}
-export interface ExecOptions {
-    /** AbortSignal to cancel the process */
-    signal?: AbortSignal;
-    /** Timeout in milliseconds */
-    timeout?: number;
-}
+export type { ExecOptions, ExecResult } from "../exec.js";
 /**
  * UI context for hooks to request interactive UI from the harness.
  * Each mode (interactive, RPC, print) provides its own implementation.
@@ -36,7 +27,7 @@ export interface HookUIContext {
      * @param options - Array of string options
      * @returns Selected option string, or null if cancelled
      */
-    select(title: string, options: string[]): Promise<string | null>;
+    select(title: string, options: string[]): Promise<string | undefined>;
     /**
      * Show a confirmation dialog.
      * @returns true if confirmed, false if cancelled
@@ -44,85 +35,271 @@ export interface HookUIContext {
     confirm(title: string, message: string): Promise<boolean>;
     /**
      * Show a text input dialog.
-     * @returns User input, or null if cancelled
+     * @returns User input, or undefined if cancelled
      */
-    input(title: string, placeholder?: string): Promise<string | null>;
+    input(title: string, placeholder?: string): Promise<string | undefined>;
     /**
      * Show a notification to the user.
      */
     notify(message: string, type?: "info" | "warning" | "error"): void;
+    /**
+     * Set status text in the footer/status bar.
+     * Pass undefined as text to clear the status for this key.
+     * Text can include ANSI escape codes for styling.
+     * Note: Newlines, tabs, and carriage returns are replaced with spaces.
+     * The combined status line is truncated to terminal width.
+     * @param key - Unique key to identify this status (e.g., hook name)
+     * @param text - Status text to display, or undefined to clear
+     */
+    setStatus(key: string, text: string | undefined): void;
+    /**
+     * Show a custom component with keyboard focus.
+     * The factory receives TUI, theme, and a done() callback to close the component.
+     * Can be async for fire-and-forget work (don't await the work, just start it).
+     *
+     * @param factory - Function that creates the component. Call done() when finished.
+     * @returns Promise that resolves with the value passed to done()
+     *
+     * @example
+     * // Sync factory
+     * const result = await ctx.ui.custom((tui, theme, done) => {
+     *   const component = new MyComponent(tui, theme);
+     *   component.onFinish = (value) => done(value);
+     *   return component;
+     * });
+     *
+     * // Async factory with fire-and-forget work
+     * const result = await ctx.ui.custom(async (tui, theme, done) => {
+     *   const loader = new CancellableLoader(tui, theme.fg("accent"), theme.fg("muted"), "Working...");
+     *   loader.onAbort = () => done(null);
+     *   doWork(loader.signal).then(done);  // Don't await - fire and forget
+     *   return loader;
+     * });
+     */
+    custom<T>(factory: (tui: TUI, theme: Theme, done: (result: T) => void) => (Component & {
+        dispose?(): void;
+    }) | Promise<Component & {
+        dispose?(): void;
+    }>): Promise<T>;
+    /**
+     * Set the text in the core input editor.
+     * Use this to pre-fill the input box with generated content (e.g., prompt templates, extracted questions).
+     * @param text - Text to set in the editor
+     */
+    setEditorText(text: string): void;
+    /**
+     * Get the current text from the core input editor.
+     * @returns Current editor text
+     */
+    getEditorText(): string;
+    /**
+     * Show a multi-line editor for text editing.
+     * Supports Ctrl+G to open external editor ($VISUAL or $EDITOR).
+     * @param title - Title describing what is being edited
+     * @param prefill - Optional initial text
+     * @returns Edited text, or undefined if cancelled (Escape)
+     */
+    editor(title: string, prefill?: string): Promise<string | undefined>;
+    /**
+     * Get the current theme for styling text with ANSI codes.
+     * Use theme.fg() and theme.bg() to style status text.
+     *
+     * @example
+     * const theme = ctx.ui.theme;
+     * ctx.ui.setStatus("my-hook", theme.fg("success", "✓") + " Ready");
+     */
+    readonly theme: Theme;
 }
 /**
  * Context passed to hook event handlers.
+ * For command handlers, see HookCommandContext which extends this with session control methods.
  */
-export interface HookEventContext {
-    /** Execute a command and return stdout/stderr/code */
-    exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+export interface HookContext {
     /** UI methods for user interaction */
     ui: HookUIContext;
     /** Whether UI is available (false in print mode) */
     hasUI: boolean;
     /** Current working directory */
     cwd: string;
-    /** Path to session file, or null if --no-session */
-    sessionFile: string | null;
+    /** Session manager (read-only) - use pi.sendMessage()/pi.appendEntry() for writes */
+    sessionManager: ReadonlySessionManager;
+    /** Model registry - use for API key resolution and model retrieval */
+    modelRegistry: ModelRegistry;
+    /** Current model (may be undefined if no model is selected yet) */
+    model: Model<any> | undefined;
+    /** Whether the agent is idle (not streaming) */
+    isIdle(): boolean;
+    /** Abort the current agent operation (fire-and-forget, does not wait) */
+    abort(): void;
+    /** Whether there are queued messages waiting to be processed */
+    hasQueuedMessages(): boolean;
 }
 /**
- * Base fields shared by all session events.
- */
-interface SessionEventBase {
-    type: "session";
-    /** All session entries (including pre-compaction history) */
-    entries: SessionEntry[];
-    /** Current session file path, or null in --no-session mode */
-    sessionFile: string | null;
-    /** Previous session file path, or null for "start" and "new" */
-    previousSessionFile: string | null;
-}
-/**
- * Event data for session events.
- * Discriminated union based on reason.
- *
- * Lifecycle:
- * - start: Initial session load
- * - before_switch / switch: Session switch (e.g., /resume command)
- * - before_new / new: New session (e.g., /new command)
- * - before_branch / branch: Session branch (e.g., /branch command)
- * - before_compact / compact: Before/after context compaction
- * - shutdown: Process exit (SIGINT/SIGTERM)
+ * Extended context for slash command handlers.
+ * Includes session control methods that are only safe in user-initiated commands.
  *
- * "before_*" events fire before the action and can be cancelled via SessionEventResult.
- * Other events fire after the action completes.
+ * These methods are not available in event handlers because they can cause
+ * deadlocks when called from within the agent loop (e.g., tool_call, context events).
  */
-export type SessionEvent = (SessionEventBase & {
-    reason: "start" | "switch" | "new" | "before_switch" | "before_new" | "shutdown";
-}) | (SessionEventBase & {
-    reason: "branch" | "before_branch";
-    /** Index of the turn to branch from */
-    targetTurnIndex: number;
-}) | (SessionEventBase & {
-    reason: "before_compact";
-    cutPoint: CutPointResult;
-    /** Summary from previous compaction, if any. Include this in your summary to preserve context. */
-    previousSummary?: string;
-    /** Messages that will be summarized and discarded */
-    messagesToSummarize: AppMessage[];
-    /** Messages that will be kept after the summary (recent turns) */
-    messagesToKeep: AppMessage[];
-    tokensBefore: number;
+export interface HookCommandContext extends HookContext {
+    /** Wait for the agent to finish streaming */
+    waitForIdle(): Promise<void>;
+    /**
+     * Start a new session, optionally with a setup callback to initialize it.
+     * The setup callback receives a writable SessionManager for the new session.
+     *
+     * @param options.parentSession - Path to parent session for lineage tracking
+     * @param options.setup - Async callback to initialize the new session (e.g., append messages)
+     * @returns Object with `cancelled: true` if a hook cancelled the new session
+     *
+     * @example
+     * // Handoff: summarize current session and start fresh with context
+     * await ctx.newSession({
+     *   parentSession: ctx.sessionManager.getSessionFile(),
+     *   setup: async (sm) => {
+     *     sm.appendMessage({ role: "user", content: [{ type: "text", text: summary }] });
+     *   }
+     * });
+     */
+    newSession(options?: {
+        parentSession?: string;
+        setup?: (sessionManager: SessionManager) => Promise<void>;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+    /**
+     * Branch from a specific entry, creating a new session file.
+     *
+     * @param entryId - ID of the entry to branch from
+     * @returns Object with `cancelled: true` if a hook cancelled the branch
+     */
+    branch(entryId: string): Promise<{
+        cancelled: boolean;
+    }>;
+    /**
+     * Navigate to a different point in the session tree (in-place).
+     *
+     * @param targetId - ID of the entry to navigate to
+     * @param options.summarize - Whether to summarize the abandoned branch
+     * @returns Object with `cancelled: true` if a hook cancelled the navigation
+     */
+    navigateTree(targetId: string, options?: {
+        summarize?: boolean;
+    }): Promise<{
+        cancelled: boolean;
+    }>;
+}
+/** Fired on initial session load */
+export interface SessionStartEvent {
+    type: "session_start";
+}
+/** Fired before switching to another session (can be cancelled) */
+export interface SessionBeforeSwitchEvent {
+    type: "session_before_switch";
+    /** Reason for the switch */
+    reason: "new" | "resume";
+    /** Session file we're switching to (only for "resume") */
+    targetSessionFile?: string;
+}
+/** Fired after switching to another session */
+export interface SessionSwitchEvent {
+    type: "session_switch";
+    /** Reason for the switch */
+    reason: "new" | "resume";
+    /** Session file we came from */
+    previousSessionFile: string | undefined;
+}
+/** Fired before branching a session (can be cancelled) */
+export interface SessionBeforeBranchEvent {
+    type: "session_before_branch";
+    /** ID of the entry to branch from */
+    entryId: string;
+}
+/** Fired after branching a session */
+export interface SessionBranchEvent {
+    type: "session_branch";
+    previousSessionFile: string | undefined;
+}
+/** Fired before context compaction (can be cancelled or customized) */
+export interface SessionBeforeCompactEvent {
+    type: "session_before_compact";
+    /** Compaction preparation with messages to summarize, file ops, previous summary, etc. */
+    preparation: CompactionPreparation;
+    /** Branch entries (root to current leaf). Use to inspect custom state or previous compactions. */
+    branchEntries: SessionEntry[];
+    /** Optional user-provided instructions for the summary */
     customInstructions?: string;
-    model: Model<any>;
-    /** Resolve API key for any model (checks settings, OAuth, env vars) */
-    resolveApiKey: (model: Model<any>) => Promise<string | undefined>;
     /** Abort signal - hooks should pass this to LLM calls and check it periodically */
     signal: AbortSignal;
-}) | (SessionEventBase & {
-    reason: "compact";
+}
+/** Fired after context compaction */
+export interface SessionCompactEvent {
+    type: "session_compact";
     compactionEntry: CompactionEntry;
-    tokensBefore: number;
     /** Whether the compaction entry was provided by a hook */
     fromHook: boolean;
-});
+}
+/** Fired on process exit (SIGINT/SIGTERM) */
+export interface SessionShutdownEvent {
+    type: "session_shutdown";
+}
+/** Preparation data for tree navigation (used by session_before_tree event) */
+export interface TreePreparation {
+    /** Node being switched to */
+    targetId: string;
+    /** Current active leaf (being abandoned), null if no current position */
+    oldLeafId: string | null;
+    /** Common ancestor of target and old leaf, null if no common ancestor */
+    commonAncestorId: string | null;
+    /** Entries to summarize (old leaf back to common ancestor or compaction) */
+    entriesToSummarize: SessionEntry[];
+    /** Whether user chose to summarize */
+    userWantsSummary: boolean;
+}
+/** Fired before navigating to a different node in the session tree (can be cancelled) */
+export interface SessionBeforeTreeEvent {
+    type: "session_before_tree";
+    /** Preparation data for the navigation */
+    preparation: TreePreparation;
+    /** Abort signal - honors Escape during summarization (model available via ctx.model) */
+    signal: AbortSignal;
+}
+/** Fired after navigating to a different node in the session tree */
+export interface SessionTreeEvent {
+    type: "session_tree";
+    /** The new active leaf, null if navigated to before first entry */
+    newLeafId: string | null;
+    /** Previous active leaf, null if there was no position */
+    oldLeafId: string | null;
+    /** Branch summary entry if one was created */
+    summaryEntry?: BranchSummaryEntry;
+    /** Whether summary came from hook */
+    fromHook?: boolean;
+}
+/** Union of all session event types */
+export type SessionEvent = SessionStartEvent | SessionBeforeSwitchEvent | SessionSwitchEvent | SessionBeforeBranchEvent | SessionBranchEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent;
+/**
+ * Event data for context event.
+ * Fired before each LLM call, allowing hooks to modify context non-destructively.
+ * Original session messages are NOT modified - only the messages sent to the LLM are affected.
+ */
+export interface ContextEvent {
+    type: "context";
+    /** Messages about to be sent to the LLM (deep copy, safe to modify) */
+    messages: AgentMessage[];
+}
+/**
+ * Event data for before_agent_start event.
+ * Fired after user submits a prompt but before the agent loop starts.
+ * Allows hooks to inject context that will be persisted and visible in TUI.
+ */
+export interface BeforeAgentStartEvent {
+    type: "before_agent_start";
+    /** The user's prompt text */
+    prompt: string;
+    /** Any images attached to the prompt */
+    images?: ImageContent[];
+}
 /**
  * Event data for agent_start event.
  * Fired when an agent loop starts (once per user prompt).
@@ -135,7 +312,7 @@ export interface AgentStartEvent {
  */
 export interface AgentEndEvent {
     type: "agent_end";
-    messages: AppMessage[];
+    messages: AgentMessage[];
 }
 /**
  * Event data for turn_start event.
@@ -151,7 +328,7 @@ export interface TurnStartEvent {
 export interface TurnEndEvent {
     type: "turn_end";
     turnIndex: number;
-    message: AppMessage;
+    message: AgentMessage;
     toolResults: ToolResultMessage[];
 }
 /**
@@ -194,7 +371,7 @@ export interface ReadToolResultEvent extends ToolResultEventBase {
 /** Tool result event for edit tool */
 export interface EditToolResultEvent extends ToolResultEventBase {
     toolName: "edit";
-    details: undefined;
+    details: EditToolDetails | undefined;
 }
 /** Tool result event for write tool */
 export interface WriteToolResultEvent extends ToolResultEventBase {
@@ -237,7 +414,15 @@ export declare function isLsToolResult(e: ToolResultEvent): e is LsToolResultEve
 /**
  * Union of all hook event types.
  */
-export type HookEvent = SessionEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | ToolCallEvent | ToolResultEvent;
+export type HookEvent = SessionEvent | ContextEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | ToolCallEvent | ToolResultEvent;
+/**
+ * Return type for context event handlers.
+ * Allows hooks to modify messages before they're sent to the LLM.
+ */
+export interface ContextEventResult {
+    /** Modified messages to send instead of the original */
+    messages?: Message[];
+}
 /**
  * Return type for tool_call event handlers.
  * Allows hooks to block tool execution.
@@ -261,39 +446,166 @@ export interface ToolResultEventResult {
     isError?: boolean;
 }
 /**
- * Return type for session event handlers.
- * Allows hooks to cancel "before_*" actions.
+ * Return type for before_agent_start event handlers.
+ * Allows hooks to inject context before the agent runs.
  */
-export interface SessionEventResult {
-    /** If true, cancel the pending action (switch, clear, or branch) */
+export interface BeforeAgentStartEventResult {
+    /** Message to inject into context (persisted to session, visible in TUI) */
+    message?: Pick<HookMessage, "customType" | "content" | "display" | "details">;
+}
+/** Return type for session_before_switch handlers */
+export interface SessionBeforeSwitchResult {
+    /** If true, cancel the switch */
+    cancel?: boolean;
+}
+/** Return type for session_before_branch handlers */
+export interface SessionBeforeBranchResult {
+    /**
+     * If true, abort the branch entirely. No new session file is created,
+     * conversation stays unchanged.
+     */
     cancel?: boolean;
-    /** If true (for before_branch only), skip restoring conversation to branch point while still creating the branched session file */
+    /**
+     * If true, the branch proceeds (new session file created, session state updated)
+     * but the in-memory conversation is NOT rewound to the branch point.
+     *
+     * Use case: git-checkpoint hook that restores code state separately.
+     * The hook handles state restoration itself, so it doesn't want the
+     * agent's conversation to be rewound (which would lose recent context).
+     *
+     * - `cancel: true` → nothing happens, user stays in current session
+     * - `skipConversationRestore: true` → branch happens, but messages stay as-is
+     * - neither → branch happens AND messages rewind to branch point (default)
+     */
     skipConversationRestore?: boolean;
-    /** Custom compaction entry (for before_compact event) */
-    compactionEntry?: CompactionEntry;
+}
+/** Return type for session_before_compact handlers */
+export interface SessionBeforeCompactResult {
+    /** If true, cancel the compaction */
+    cancel?: boolean;
+    /** Custom compaction result - SessionManager adds id/parentId */
+    compaction?: CompactionResult;
+}
+/** Return type for session_before_tree handlers */
+export interface SessionBeforeTreeResult {
+    /** If true, cancel the navigation entirely */
+    cancel?: boolean;
+    /**
+     * Custom summary (skips default summarizer).
+     * Only used if preparation.userWantsSummary is true.
+     */
+    summary?: {
+        summary: string;
+        details?: unknown;
+    };
 }
 /**
  * Handler function type for each event.
+ * Handlers can return R, undefined, or void (bare return statements).
+ */
+export type HookHandler<E, R = undefined> = (event: E, ctx: HookContext) => Promise<R | void> | R | void;
+export interface HookMessageRenderOptions {
+    /** Whether the view is expanded */
+    expanded: boolean;
+}
+/**
+ * Renderer for hook messages.
+ * Hooks register these to provide custom TUI rendering for their message types.
  */
-export type HookHandler<E, R = void> = (event: E, ctx: HookEventContext) => Promise<R>;
+export type HookMessageRenderer<T = unknown> = (message: HookMessage<T>, options: HookMessageRenderOptions, theme: Theme) => Component | undefined;
+/**
+ * Command registration options.
+ */
+export interface RegisteredCommand {
+    name: string;
+    description?: string;
+    handler: (args: string, ctx: HookCommandContext) => Promise<void>;
+}
 /**
  * HookAPI passed to hook factory functions.
- * Hooks use pi.on() to subscribe to events and pi.send() to inject messages.
+ * Hooks use pi.on() to subscribe to events and pi.sendMessage() to inject messages.
  */
 export interface HookAPI {
-    on(event: "session", handler: HookHandler<SessionEvent, SessionEventResult | void>): void;
+    on(event: "session_start", handler: HookHandler<SessionStartEvent>): void;
+    on(event: "session_before_switch", handler: HookHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>): void;
+    on(event: "session_switch", handler: HookHandler<SessionSwitchEvent>): void;
+    on(event: "session_before_branch", handler: HookHandler<SessionBeforeBranchEvent, SessionBeforeBranchResult>): void;
+    on(event: "session_branch", handler: HookHandler<SessionBranchEvent>): void;
+    on(event: "session_before_compact", handler: HookHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>): void;
+    on(event: "session_compact", handler: HookHandler<SessionCompactEvent>): void;
+    on(event: "session_shutdown", handler: HookHandler<SessionShutdownEvent>): void;
+    on(event: "session_before_tree", handler: HookHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
+    on(event: "session_tree", handler: HookHandler<SessionTreeEvent>): void;
+    on(event: "context", handler: HookHandler<ContextEvent, ContextEventResult>): void;
+    on(event: "before_agent_start", handler: HookHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
     on(event: "agent_start", handler: HookHandler<AgentStartEvent>): void;
     on(event: "agent_end", handler: HookHandler<AgentEndEvent>): void;
     on(event: "turn_start", handler: HookHandler<TurnStartEvent>): void;
     on(event: "turn_end", handler: HookHandler<TurnEndEvent>): void;
-    on(event: "tool_call", handler: HookHandler<ToolCallEvent, ToolCallEventResult | undefined>): void;
-    on(event: "tool_result", handler: HookHandler<ToolResultEvent, ToolResultEventResult | undefined>): void;
+    on(event: "tool_call", handler: HookHandler<ToolCallEvent, ToolCallEventResult>): void;
+    on(event: "tool_result", handler: HookHandler<ToolResultEvent, ToolResultEventResult>): void;
     /**
-     * Send a message to the agent.
-     * If the agent is streaming, the message is queued.
-     * If the agent is idle, a new agent loop is started.
+     * Send a custom message to the session. Creates a CustomMessageEntry that
+     * participates in LLM context and can be displayed in the TUI.
+     *
+     * Use this when you want the LLM to see the message content.
+     * For hook state that should NOT be sent to the LLM, use appendEntry() instead.
+     *
+     * @param message - The message to send
+     * @param message.customType - Identifier for your hook (used for filtering on reload)
+     * @param message.content - Message content (string or TextContent/ImageContent array)
+     * @param message.display - Whether to show in TUI (true = styled display, false = hidden)
+     * @param message.details - Optional hook-specific metadata (not sent to LLM)
+     * @param triggerTurn - If true and agent is idle, triggers a new LLM turn. Default: false.
+     *                      If agent is streaming, message is queued and triggerTurn is ignored.
      */
-    send(text: string, attachments?: Attachment[]): void;
+    sendMessage<T = unknown>(message: Pick<HookMessage<T>, "customType" | "content" | "display" | "details">, triggerTurn?: boolean): void;
+    /**
+     * Append a custom entry to the session for hook state persistence.
+     * Creates a CustomEntry that does NOT participate in LLM context.
+     *
+     * Use this to store hook-specific data that should persist across session reloads
+     * but should NOT be sent to the LLM. On reload, scan session entries for your
+     * customType to reconstruct hook state.
+     *
+     * For messages that SHOULD be sent to the LLM, use sendMessage() instead.
+     *
+     * @param customType - Identifier for your hook (used for filtering on reload)
+     * @param data - Hook-specific data to persist (must be JSON-serializable)
+     *
+     * @example
+     * // Store permission state
+     * pi.appendEntry("permissions", { level: "full", grantedAt: Date.now() });
+     *
+     * // On reload, reconstruct state from entries
+     * pi.on("session", async (event, ctx) => {
+     *   if (event.reason === "start") {
+     *     const entries = event.sessionManager.getEntries();
+     *     const myEntries = entries.filter(e => e.type === "custom" && e.customType === "permissions");
+     *     // Reconstruct state from myEntries...
+     *   }
+     * });
+     */
+    appendEntry<T = unknown>(customType: string, data?: T): void;
+    /**
+     * Register a custom renderer for CustomMessageEntry with a specific customType.
+     * The renderer is called when rendering the entry in the TUI.
+     * Return nothing to use the default renderer.
+     */
+    registerMessageRenderer<T = unknown>(customType: string, renderer: HookMessageRenderer<T>): void;
+    /**
+     * Register a custom slash command.
+     * Handler receives HookCommandContext with session control methods.
+     */
+    registerCommand(name: string, options: {
+        description?: string;
+        handler: RegisteredCommand["handler"];
+    }): void;
+    /**
+     * Execute a shell command and return stdout/stderr/code.
+     * Supports timeout and abort signal.
+     */
+    exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
 }
 /**
  * Hook factory function type.
@@ -308,5 +620,4 @@ export interface HookError {
     event: string;
     error: string;
 }
-export {};
 //# sourceMappingURL=types.d.ts.map