co-mono/packages/coding-agent/UNRELEASED_OLD.md

Breaking Changes

• Session tree structure (v2): Sessions now store entries as a tree with id/parentId fields, enabling in-place branching without creating new files. Existing v1 sessions are auto-migrated on load.
• SessionManager API:
  • saveXXX() renamed to appendXXX() (e.g., appendMessage, appendCompaction)
  • branchInPlace() renamed to branch()
  • reset() renamed to newSession()
  • createBranchedSessionFromEntries(entries, index) replaced with createBranchedSession(leafId)
  • saveCompaction(entry) replaced with appendCompaction(summary, firstKeptEntryId, tokensBefore)
  • getEntries() now excludes the session header (use getHeader() separately)
  • New methods: getTree(), getPath(), getLeafUuid(), getLeafEntry(), getEntry(), branchWithSummary()
  • New appendCustomEntry(customType, data) for hooks to store custom data (not in LLM context)
  • New appendCustomMessageEntry(customType, content, display, details?) for hooks to inject messages into LLM context
• Compaction API:
  • CompactionEntry<T> and CompactionResult<T> are now generic with optional details?: T for hook-specific data
  • compact() now returns CompactionResult ({ summary, firstKeptEntryId, tokensBefore, details? }) instead of CompactionEntry
  • appendCompaction() now accepts optional details parameter
  • CompactionEntry.firstKeptEntryIndex replaced with firstKeptEntryId
  • prepareCompaction() now returns firstKeptEntryId in its result
• Hook types:
  • SessionEventBase no longer has sessionManager/modelRegistry - access them via HookEventContext instead
  • HookEventContext now has sessionManager and modelRegistry (moved from events)
  • HookEventContext no longer has exec() - use pi.exec() instead
  • HookCommandContext no longer has exec() - use pi.exec() instead
  • before_compact event passes preparation: CompactionPreparation and previousCompactions: CompactionEntry[] (newest first)
  • before_switch event now has targetSessionFile, switch event has previousSessionFile
  • Removed resolveApiKey (use modelRegistry.getApiKey(model))
  • Hooks can return compaction.details to store custom data (e.g., ArtifactIndex for structured compaction)
• Hook API:
  • pi.send(text, attachments?) replaced with pi.sendMessage(message, triggerTurn?) which creates CustomMessageEntry instead of user messages
  • New pi.appendEntry(customType, data?) to persist hook state (does NOT participate in LLM context)
  • New pi.registerCommand(name, options) to register custom slash commands
  • New pi.registerMessageRenderer(customType, renderer) to register custom renderers for hook messages
  • New pi.exec(command, args, options?) to execute shell commands (moved from HookEventContext/HookCommandContext)
  • HookMessageRenderer type: (message: HookMessage, options, theme) => Component | null
  • Renderers return inner content; the TUI wraps it in a styled Box
  • New types: HookMessage<T>, RegisteredCommand, HookCommandContext
  • Handler types renamed: SendHandler → SendMessageHandler, new AppendEntryHandler
• SessionManager:
  • getSessionFile() now returns string | undefined (undefined for in-memory sessions)
• Themes: Custom themes must add customMessageBg, customMessageText, customMessageLabel color tokens

Added

• enabledModels setting: Configure whitelisted models in settings.json (same format as --models CLI flag). CLI --models takes precedence over the setting.

Changed

• 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<T> for hook state persistence, CustomMessageEntry<T> for hook-injected context messages, 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.
• TUI: CustomMessageEntry renders with purple styling (customMessageBg, customMessageText, customMessageLabel theme colors). Entries with display: false are hidden.
• AgentSession: New sendHookMessage(message, triggerTurn?) method for hooks to inject messages. Handles queuing during streaming, direct append when idle, and optional turn triggering.
• HookMessage: New message type with role: "hookMessage" for hook-injected messages in agent events. Use isHookMessage(msg) type guard to identify them. These are converted to user messages for LLM context via messageTransformer.
• Agent.prompt(): Now accepts AppMessage directly (in addition to string, attachments?) for custom message types like HookMessage.

Fixed

• Edit tool fails on Windows due to CRLF line endings: Files with CRLF line endings now match correctly when LLMs send LF-only text. Line endings are normalized before matching and restored to original style on write. (#355)
• Session file validation: findMostRecentSession() now validates session headers before returning, preventing non-session JSONL files from being loaded
• Compaction error handling: generateSummary() and generateTurnPrefixSummary() now throw on LLM errors instead of returning empty strings