diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 8441876d..d31056bd 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -30,7 +30,7 @@
 
 - **Entry IDs**: Session entries now use short 8-character hex IDs instead of full UUIDs
 - **API key priority**: `ANTHROPIC_OAUTH_TOKEN` now takes precedence over `ANTHROPIC_API_KEY`
-- **New entry types**: `BranchSummaryEntry` for branch context, `CustomEntry` for hook data, `LabelEntry` for user-defined bookmarks
+- **New entry types**: `BranchSummaryEntry` for branch context, `CustomEntry<T>` for hook state persistence, `LabelEntry` for user-defined bookmarks
 - **Entry labels**: New `getLabel(id)` and `appendLabelChange(targetId, label)` methods for labeling entries. Labels are included in `SessionTreeNode` for UI/export.
 
 ### Fixed
diff --git a/packages/coding-agent/docs/session-tree-plan.md b/packages/coding-agent/docs/session-tree-plan.md
index fbc60e81..1f058d5d 100644
--- a/packages/coding-agent/docs/session-tree-plan.md
+++ b/packages/coding-agent/docs/session-tree-plan.md
@@ -93,14 +93,14 @@ Questions to resolve:
 
 ### CustomMessageEntry<T>
 
-Hooks can define their own custom message entry types and inject them into the session.
+Hook-injected messages that participate in LLM context. Unlike `CustomEntry<T>` (for hook state only), these are sent to the model.
 
 ```typescript
 export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
   type: "custom_message";
   customType: string;           // Hook identifier
   content: (string | Attachment)[];  // Message content
-  details?: T;                  // Hook-specific data (like tool result details)
+  details?: T;                  // Hook-specific data for state reconstruction on reload
   display: boolean;             // Whether to display in TUI
 }
 ```
@@ -115,6 +115,8 @@ Behavior:
 - [ ] Define injection mechanism for hooks to add CustomMessageEntry
 - [ ] Hook registration for custom renderers
 
+See also: `CustomEntry<T>` for storing hook state that does NOT participate in context.
+
 ### HTML Export
 
 - [ ] Add collapsible sidebar showing full tree structure
diff --git a/packages/coding-agent/src/core/session-manager.ts b/packages/coding-agent/src/core/session-manager.ts
index 9f724372..e59a2934 100644
--- a/packages/coding-agent/src/core/session-manager.ts
+++ b/packages/coding-agent/src/core/session-manager.ts
@@ -61,11 +61,20 @@ export interface BranchSummaryEntry extends SessionEntryBase {
 	summary: string;
 }
 
-/** Custom entry for hooks. Use customType to identify your hook's entries. */
-export interface CustomEntry extends SessionEntryBase {
+/**
+ * Custom entry for hooks to store hook-specific data in the session.
+ * Use customType to identify your hook's entries.
+ *
+ * Purpose: Persist hook state across session reloads. On reload, hooks can
+ * scan entries for their customType and reconstruct internal state.
+ *
+ * Does NOT participate in LLM context (ignored by buildSessionContext).
+ * For injecting content into context, see CustomMessageEntry.
+ */
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
 	type: "custom";
 	customType: string;
-	data?: unknown;
+	data?: T;
 }
 
 /** Label entry for user-defined bookmarks/markers on entries. */