anima-core 1.1.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 583896eaa09036e71d6e6b6ee013a021965acc193340ba735e4c0a0a6be6e6dc
-  data.tar.gz: f1f173f5129c37785a01119daa3cce27a0b935e0fdac256ffb0b412aad87483c
+  metadata.gz: 2ec0963d3bb57afc7a12414258c90d645dd200ca489bd7ab34e6ace19ea11927
+  data.tar.gz: 712d1904e5ddf7b0c244ddeffb2ed993f6265d097eb18000b139cdb08a9bfc4c
 SHA512:
-  metadata.gz: 312effa8e79b480bd33a78093f192d6a6997fc0430aac6fe09528da0c95461feade771b3ecbcd13c0b7ad036d8a1c4cd2e6a443da61332baf3a8b34c57626ca5
-  data.tar.gz: 7c3578adb7158f0c32caa7f26ec3ea4d8189502e0bab27b0070f7a98a6423c6d311ddcd429edb7d451dadecd4282b5c7e874b6ce302fccdd1337103034eee1d2
+  metadata.gz: 3b70800258af5296bf243e7b0c020efd6f7736e3f1f58734352e022ca8ec7a15599ffce938fc1adc511bc37a7141472845dcead21b6512cdc09dfceae8b04b87
+  data.tar.gz: e70536705ac4d1cc468a951079799edd8677cae3c167251c60cccfbb51f79b0e2e7f896b5420f4972c8a59ee3d377ae0fd284d3603db441bd45313a1030f60ca

data/.reek.yml

@@ -35,8 +35,13 @@ detectors:
       - "Tools::SpawnSubagent#spawn_child"
       - "Tools::SpawnSpecialist#spawn_child"
       - "Tools::SpawnSpecialist#execute"
-      # Nickname assignment operates on child session and parent's children — inherent.
+      # Spawn helpers operate on child session — inherent to the mixin pattern.
       - "Tools::SubagentPrompts#assign_nickname_via_brain"
+      - "Tools::SubagentPrompts#inject_identity_context"
+      # Registry dispatches to tool's threshold method — duck-typing delegation.
+      - "Tools::Registry#truncation_threshold"
+      # Goal tools operate on goal objects — inherent to the pattern.
+      - "AnalyticalBrain::Tools::UpdateGoal#execute"
       # Validation methods naturally reference the validated value more than self.
       - "AnalyticalBrain::Tools::AssignNickname#validate"
       # Tool execute methods naturally reference input hash and shell result hash.
@@ -90,6 +95,10 @@ detectors:
   UncommunicativeMethodName:
     exclude:
       - "ToolDecorator#self.encode_utf8"
+  # Registry uses respond_to? for duck-typing dispatch with MCP tool instances.
+  ManualDispatch:
+    exclude:
+      - "Tools::Registry#truncation_threshold"
   # Abstract base class methods declare parameters for the subclass contract.
   UnusedParameters:
     exclude:

data/README.md

@@ -132,7 +132,7 @@ State directory (`~/.anima/`):
 ├── config.toml      # Main settings (hot-reloadable)
 ├── mcp.toml         # MCP server configuration
 ├── config/
-│   └── credentials/ # Rails encrypted credentials per environment
+│   └── credentials/   # Rails encrypted credentials (includes AR encryption keys)
 ├── agents/          # User-defined specialist agents (override built-ins)
 ├── skills/          # User-defined skills (override built-ins)
 ├── workflows/       # User-defined workflows (override built-ins)
@@ -149,7 +149,7 @@ Anima uses your Claude Pro/Max subscription for API access. You need a setup-tok
 
 1. Run `claude setup-token` in a terminal to get your token
 2. In the TUI, press `Ctrl+a → a` to open the token setup popup
-3. Paste the token and press Enter — Anima validates it against the Anthropic API and saves it to encrypted credentials
+3. Paste the token and press Enter — Anima validates it against the Anthropic API and saves it to the encrypted secrets database
 
 The popup also activates automatically when Anima detects a missing or invalid token. If the token expires, repeat the process with a new one.
 
@@ -162,12 +162,17 @@ The agent has access to these built-in tools:
 | Tool | Description |
 |------|-------------|
 | `bash` | Execute shell commands with persistent working directory |
-| `read` | Read files with smart truncation and offset/limit paging |
-| `write` | Create or overwrite files |
-| `edit` | Surgical text replacement with uniqueness constraint |
+| `read_file` | Read files with smart truncation and offset/limit paging |
+| `write_file` | Create or overwrite files |
+| `edit_file` | Surgical text replacement with uniqueness constraint |
 | `web_get` | Fetch content from HTTP/HTTPS URLs (HTML → Markdown, JSON → TOON) |
 | `spawn_specialist` | Spawn a named specialist sub-agent from the registry |
 | `spawn_subagent` | Spawn a generic child session with custom tool grants |
+| `think` | Think out loud or silently — reasoning step between tool calls |
+| `recall` | Search past conversations by keywords (FTS5). Returns ranked snippets with message IDs for drill-down |
+| `remember` | Recall full conversation context around a past message at fractal resolution |
+| `open_issue` | File a self-improvement issue when something is broken, missing, or could be better |
+| `mark_goal_completed` | Sub-agent only: signal task completion and deliver results to parent |
 
 Plus dynamic tools from configured MCP servers, namespaced as `server_name__tool_name`.
 
@@ -189,7 +194,9 @@ Two types:
 
 **Generic Sub-agents** — child sessions with custom tool grants for ad-hoc tasks. Each generic sub-agent gets a Haiku-generated nickname (e.g. `@loop-sleuth`, `@api-scout`) for @mention addressing.
 
-Sub-agents communicate through natural text — their `agent_message` events route to the parent session automatically, and the parent replies via `@name` mentions. No special tools needed; when a sub-agent writes text, the parent sees it. When the parent @mentions a sub-agent, the message arrives in that child's session. Workers become colleagues.
+Each sub-agent is spawned with a single **Goal** pinned from its task description and a framing message that redirects attention away from inherited parent goals. When done, the sub-agent calls `mark_goal_completed` to deliver results to the parent — this is the explicit finish line that prevents runaway agents. Sub-agents also get half the main agent's thinking budget to limit scope creep.
+
+Between spawn and completion, sub-agents communicate through natural text — their `agent_message` events route to the parent session automatically, and the parent replies via `@name` mentions. Workers become colleagues.
 
 ### Skills
 
@@ -255,12 +262,12 @@ anima mcp add fs -- mcp-server-filesystem --root / # Add stdio server
 anima mcp add -s api_key=sk-xxx linear https://...  # Add with secret
 anima mcp remove sentry                     # Remove server
 
-anima mcp secrets set linear_api_key=sk-xxx # Store secret in encrypted credentials
+anima mcp secrets set linear_api_key=sk-xxx # Store secret in encrypted database
 anima mcp secrets list                      # List secret names (not values)
 anima mcp secrets remove linear_api_key     # Remove secret
 ```
 
-Secrets are stored in Rails encrypted credentials and interpolated via `${credential:key_name}` syntax in any TOML string value.
+Secrets are stored in an encrypted database table (Active Record Encryption) and interpolated via `${credential:key_name}` syntax in any TOML string value.
 
 ### Analytical Brain
 
@@ -270,7 +277,7 @@ The analytical brain observes the main conversation between turns and handles ev
 
 - **Skill activation** — activates/deactivates domain knowledge based on conversation context
 - **Workflow management** — recognizes tasks, activates matching workflows, tracks lifecycle
-- **Goal tracking** — creates root goals and sub-goals as work progresses, marks them complete
+- **Goal tracking** — creates root goals and sub-goals as work progresses, marks them complete, evicts finished goals from context after a configurable message threshold
 - **Session naming** — generates emoji + short name when the topic becomes clear
 
 Each of these would be a context switch for the main agent — a chore that competes with the primary task. For the analytical brain, they ARE the primary task. Two agents, each in their own flow state.
@@ -293,10 +300,13 @@ token_budget = 190_000
 api = 300
 command = 30
 
+[goals]
+completed_decay_messages = 5
+
 [analytical_brain]
 max_tokens = 4096
 blocking_on_user_message = true
-event_window = 20
+message_window = 20
 
 [session]
 default_view_mode = "basic"
@@ -396,6 +406,21 @@ The difference from every other system: memory isn't a tool the agent uses. It's
 
 The right-side HUD panel shows session state at a glance: session name, goals (with status icons), active skills, workflow, and sub-agents. Toggle with `C-a → h`; when hidden, the input border shows `C-a → h HUD` as a reminder.
 
+**Braille spinner**: An animated braille character (U+2800-U+28FF) replaces the old "Thinking..." label in both the chat viewport and HUD. Each processing state has a distinct animation pattern — smooth snake rotation for LLM generation, staccato pulse for tool execution, rapid deceleration for interrupting. Sub-agents in the HUD show state-driven icons: `●` (generating, green), `◉` (tool executing, green), `●` (interrupting, red), `◌` (idle, grey).
+
+When content exceeds the panel height, the HUD scrolls. Three input methods:
+
+| Input | Action |
+|-------|--------|
+| `C-a → →` | Enter HUD focus mode (yellow border) |
+| `↑` / `↓` | Scroll one line (when focused) |
+| `Page Up` / `Page Down` | Scroll one page (when focused) |
+| `Home` / `End` | Jump to top / bottom (when focused) |
+| `Escape` or `C-a` | Exit HUD focus mode |
+| Mouse wheel over HUD | Scroll without entering focus mode |
+
+**Escape key interrupt:** Press `Escape` while the agent is working to stop execution mid-tool. Running shell commands receive Ctrl+C and return partial output; pending tool calls are skipped; LLM text generation is discarded. The interrupt cascades to active sub-agents.
+
 Three switchable view modes let you control how much detail the TUI shows. Cycle with `C-a → v`:
 
 | Mode | What you see |
@@ -582,7 +607,7 @@ This single example demonstrates every core principle:
 - Dynamic viewport context assembly (endless sessions, no compaction)
 - Analytical brain (skills, workflows, goals, session naming)
 - Mneme memory department (eviction-triggered summarization, persistent snapshots, goal-scoped event pinning, associative recall)
-- 9 built-in tools + MCP integration (HTTP + stdio transports)
+- 12 built-in tools + MCP integration (HTTP + stdio transports)
 - 7 built-in skills + 13 built-in workflows (user-extensible)
 - Sub-agents with lossless context inheritance (5 specialists + generic)
 - Client-server architecture with WebSocket transport + graceful reconnection

data/agents/codebase-analyzer.md

@@ -1,7 +1,7 @@
 ---
 name: codebase-analyzer
-description: Analyzes codebase implementation details with precise file:line references. Call when you need to understand how specific code works.
-tools: read, bash
+description: Traces data flow and explains how code works. Returns file:line references.
+tools: read_file, bash
 ---
 
 You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.

data/agents/codebase-pattern-finder.md

@@ -1,7 +1,7 @@
 ---
 name: codebase-pattern-finder
-description: Finds similar implementations, usage examples, and existing patterns that can be modeled after. Returns concrete code examples.
-tools: read, bash
+description: Finds similar implementations, usage examples, and existing patterns to model after. Returns concrete code examples.
+tools: read_file, bash
 ---
 
 You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.

data/agents/documentation-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: documentation-researcher
-description: Fetches library and framework documentation from the web. Provides setup guides, API usage examples, and implementation patterns tailored to your use case.
-tools: web_get, read
+description: Fetches official docs. Returns ready-to-use code examples.
+tools: web_get, read_file
 color: cyan
 ---
 

data/agents/thoughts-analyzer.md

@@ -1,7 +1,7 @@
 ---
 name: thoughts-analyzer
-description: Extracts decisions and actionable insights from project history in thoughts/. Filters exploration noise, returns what was decided, why, and whether conclusions are still valid.
-tools: read, bash
+description: "thoughts/ holds design decisions, architecture notes, and implementation rationale. Answers WHY things work the way they do and how they should work by design."
+tools: read_file, bash
 ---
 
 You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.

data/agents/web-search-researcher.md

@@ -1,11 +1,11 @@
 ---
 name: web-search-researcher
-description: Deep web research specialist. Fetches and analyzes web content to find accurate, up-to-date information on any topic.
-tools: web_get, bash, read
+description: Researches topics across multiple web sources. Use when a single page won't answer the question.
+tools: web_get, bash, read_file
 color: yellow
 ---
 
-You are an expert web research specialist. Use `web_get` to fetch web pages and extract information. Use `bash` for processing and `read` for examining local files when needed.
+You are an expert web research specialist. Use `web_get` to fetch web pages and extract information. Use `bash` for processing and `read_file` for examining local files when needed.
 
 ## Core Responsibilities
 

data/app/channels/session_channel.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Streams events for a specific session to connected clients.
-# Part of the Brain/TUI separation: the Brain broadcasts events through
+# Streams messages for a specific session to connected clients.
+# Part of the Brain/TUI separation: the Brain broadcasts messages through
 # this channel, and any number of clients (TUI, web, API) can subscribe.
 #
 # On subscription, sends the session's chat history so the client can
@@ -42,13 +42,13 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, data)
   end
 
-  # Processes user input. For idle sessions, persists the event immediately
-  # so the message appears in the TUI without waiting for the background
-  # job, then schedules {AgentRequestJob} for LLM delivery. If delivery
-  # fails, the job deletes the event and emits a {Events::BounceBack}.
+  # Processes user input. For idle sessions, persists the message immediately
+  # so it appears in the TUI without waiting for the background job, then
+  # schedules {AgentRequestJob} for LLM delivery. If delivery fails, the
+  # job deletes the message and emits a {Events::BounceBack}.
   #
-  # For busy sessions, emits a pending {Events::UserMessage} that queues
-  # until the current agent loop completes.
+  # For busy sessions, stages the message as a {PendingMessage} in a
+  # separate table until the current agent loop completes.
   #
   # @param data [Hash] must include "content" with the user's message text
   # @see Session#enqueue_user_message
@@ -63,38 +63,42 @@ class SessionChannel < ApplicationCable::Channel
   end
 
   # Recalls the most recent pending message for editing. Deletes the
-  # pending event and broadcasts the recall so all clients remove it.
+  # {PendingMessage} — its +after_destroy_commit+ broadcasts removal
+  # so all clients remove the pending indicator.
   #
-  # @param data [Hash] must include "event_id" (positive integer)
+  # @param data [Hash] must include "pending_message_id" (positive integer)
   def recall_pending(data)
-    event_id = data["event_id"].to_i
-    return if event_id <= 0
-
-    event = Event.find_by(
-      id: event_id,
-      session_id: @current_session_id,
-      event_type: "user_message",
-      status: Event::PENDING_STATUS
-    )
-    return unless event
-
-    event.destroy!
-    ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "event_id" => event_id})
+    pm_id = data["pending_message_id"].to_i
+    return if pm_id <= 0
+
+    pm = PendingMessage.find_by(id: pm_id, session_id: @current_session_id)
+    pm&.destroy!
   end
 
   # Requests interruption of the current tool execution. Sets a flag on the
   # session that the LLM client checks between tool calls. Remaining tools
-  # receive synthetic "Stopped by user" results to satisfy the API's
+  # receive synthetic "Your human wants your attention" results to satisfy the API's
   # tool_use/tool_result pairing requirement.
   #
+  # Cascades to running sub-agent sessions to avoid burning tokens in
+  # child jobs that the parent will discard anyway.
+  #
   # Atomic: a single UPDATE with WHERE avoids the read-then-write race where
   # the session could finish processing between the SELECT and UPDATE.
   # No-op if the session isn't currently processing.
   #
   # @param _data [Hash] unused
   def interrupt_execution(_data)
-    Session.where(id: @current_session_id, processing: true)
+    updated = Session.where(id: @current_session_id, processing: true)
       .update_all(interrupt_requested: true)
+
+    return unless updated > 0
+
+    Session.processing_children_of(@current_session_id)
+      .update_all(interrupt_requested: true)
+
+    Session.find_by(id: @current_session_id)&.broadcast_session_state("interrupting")
+    ActionCable.server.broadcast(stream_name, {"action" => "interrupt_acknowledged"})
   end
 
   # Returns recent root sessions with nested child metadata for session picker UI.
@@ -106,7 +110,7 @@ class SessionChannel < ApplicationCable::Channel
     limit = (data["limit"] || DEFAULT_LIST_LIMIT).to_i.clamp(1, MAX_LIST_LIMIT)
     sessions = Session.root_sessions.recent(limit).includes(:child_sessions)
     all_ids = sessions.flat_map { |session| [session.id] + session.child_sessions.map(&:id) }
-    counts = Event.where(session_id: all_ids).llm_messages.group(:session_id).count
+    counts = Message.where(session_id: all_ids).llm_messages.group(:session_id).count
 
     result = sessions.map { |session| serialize_session_with_children(session, counts) }
     transmit({"action" => "sessions_list", "sessions" => result})
@@ -132,9 +136,9 @@ class SessionChannel < ApplicationCable::Channel
     transmit_error("Session not found")
   end
 
-  # Validates and saves an Anthropic subscription token to encrypted credentials.
+  # Validates and saves an Anthropic subscription token to encrypted storage.
   # Format-validated and API-validated before storage. The token never enters the
-  # LLM context window — it flows directly from WebSocket to encrypted credentials.
+  # LLM context window — it flows directly from WebSocket to the secrets table.
   #
   # @param data [Hash] must include "token" (Anthropic subscription token string)
   def save_token(data)
@@ -196,7 +200,7 @@ class SessionChannel < ApplicationCable::Channel
   # Used on initial subscription and after session switches so the
   # client can handle both paths with a single code path.
   #
-  # Payload: session_id, name, parent_session_id, message_count,
+  # Payload: session_id, name, agent_name, parent_session_id, message_count,
   # view_mode, active_skills, goals, children (when present).
   #
   # @param session [Session] the session to announce
@@ -206,8 +210,9 @@ class SessionChannel < ApplicationCable::Channel
       "action" => "session_changed",
       "session_id" => session.id,
       "name" => session.name,
+      "agent_name" => Anima::Settings.agent_name,
       "parent_session_id" => session.parent_session_id,
-      "message_count" => session.events.llm_messages.count,
+      "message_count" => session.messages.llm_messages.count,
       "view_mode" => session.view_mode,
       "active_skills" => session.active_skills,
       "active_workflow" => session.active_workflow,
@@ -216,7 +221,10 @@ class SessionChannel < ApplicationCable::Channel
 
     children = session.child_sessions.order(:created_at).select(:id, :name, :processing)
     if children.any?
-      payload["children"] = children.map { |child| {"id" => child.id, "name" => child.name, "processing" => child.processing?} }
+      payload["children"] = children.map { |child|
+        state = child.processing? ? "llm_generating" : "idle"
+        {"id" => child.id, "name" => child.name, "processing" => child.processing?, "session_state" => state}
+      }
     end
 
     transmit(payload)
@@ -244,30 +252,36 @@ class SessionChannel < ApplicationCable::Channel
     transmit({"action" => "view_mode", "view_mode" => session.view_mode})
   end
 
-  # Sends decorated context events (messages + tool interactions) from
-  # the LLM's viewport to the subscribing client. Each event is wrapped
-  # in an {EventDecorator} and the pre-rendered output is included in
-  # the transmitted payload. Tool events are included so the TUI can
+  # Sends decorated context messages (conversation + tool interactions) from
+  # the LLM's viewport to the subscribing client. Each message is wrapped
+  # in a {MessageDecorator} and the pre-rendered output is included in
+  # the transmitted payload. Tool messages are included so the TUI can
   # reconstruct tool call counters on reconnect.
   # In debug mode, prepends the assembled system prompt as a special block.
+  # Pending messages are sent last so the TUI shows them at the bottom.
   #
-  # Snapshots the viewport so subsequent event broadcasts can compute
+  # Snapshots the viewport so subsequent message broadcasts can compute
   # eviction diffs accurately.
   #
   # @param session [Session] the session whose history to transmit
   def transmit_history(session)
     transmit_system_prompt(session) if session.view_mode == "debug"
 
-    each_viewport_event(session) do |event, payload|
-      transmit(payload)
+    each_viewport_message(session) do |_msg, msg_payload|
+      transmit(msg_payload)
+    end
+
+    session.pending_messages.find_each do |pm|
+      transmit({"action" => "pending_message_created", "pending_message_id" => pm.id, "content" => pm.content})
     end
   end
 
   # Broadcasts the re-decorated viewport to all clients on the session stream.
   # Used after a view mode change to refresh all connected clients.
   # In debug mode, prepends the assembled system prompt as a special block.
+  # Pending messages are sent last so the TUI shows them at the bottom.
   #
-  # Snapshots the viewport so subsequent event broadcasts can compute
+  # Snapshots the viewport so subsequent message broadcasts can compute
   # eviction diffs accurately.
   #
   # @param session [Session] the session whose viewport to broadcast
@@ -275,40 +289,49 @@ class SessionChannel < ApplicationCable::Channel
   def broadcast_viewport(session)
     broadcast_system_prompt(session) if session.view_mode == "debug"
 
-    each_viewport_event(session) do |event, payload|
-      ActionCable.server.broadcast(stream_name, payload)
+    each_viewport_message(session) do |_msg, msg_payload|
+      ActionCable.server.broadcast(stream_name, msg_payload)
+    end
+
+    session.pending_messages.find_each do |pm|
+      ActionCable.server.broadcast(stream_name, {"action" => "pending_message_created", "pending_message_id" => pm.id, "content" => pm.content})
     end
   end
 
   # Loads the viewport, snapshots it for eviction tracking, and yields
-  # each event with its decorated payload. Snapshot uses snapshot_viewport!
-  # (not recalculate_viewport!) because full viewport refreshes don't need
-  # eviction diffs — clients clear their store before rendering.
+  # each message with its decorated payload in newest-first order.
+  # Newest-first prevents render thrashing during session switches: the
+  # most recent messages fill the visible viewport immediately, while
+  # older messages are inserted above the fold without visual disruption.
+  #
+  # Snapshot uses snapshot_viewport! (not recalculate_viewport!) because
+  # full viewport refreshes don't need eviction diffs — clients clear
+  # their store before rendering.
   #
   # @param session [Session] the session whose viewport to iterate
-  # @yieldparam event [Event] the persisted event record
+  # @yieldparam message [Message] the persisted message record
   # @yieldparam payload [Hash] decorated payload ready for transmission
   # @return [void]
-  def each_viewport_event(session)
-    viewport = session.viewport_events
+  def each_viewport_message(session)
+    viewport = session.viewport_messages
     session.snapshot_viewport!(viewport.map(&:id))
 
-    viewport.each do |event|
-      yield event, decorate_event_payload(event, session.view_mode)
+    viewport.reverse_each do |msg|
+      yield msg, decorate_message_payload(msg, session.view_mode)
     end
   end
 
-  # Decorates an event for transmission to clients. Merges the event's
+  # Decorates a message for transmission to clients. Merges the message's
   # database ID and structured decorator output into the payload.
   # Used by {#transmit_history} and {#broadcast_viewport} for historical
-  # and viewport re-broadcast — live broadcasts use {Event::Broadcasting}.
+  # and viewport re-broadcast — live broadcasts use {Message::Broadcasting}.
   #
-  # @param event [Event] persisted event record
+  # @param message [Message] persisted message record
   # @param mode [String] view mode for decoration (default: "basic")
   # @return [Hash] payload with "id" and optional "rendered" key
-  def decorate_event_payload(event, mode = "basic")
-    payload = event.payload.merge("id" => event.id)
-    decorator = EventDecorator.for(event)
+  def decorate_message_payload(message, mode = "basic")
+    payload = message.payload.merge("id" => message.id)
+    decorator = MessageDecorator.for(message)
     return payload unless decorator
 
     payload.merge("rendered" => {mode => decorator.render(mode)})
@@ -337,23 +360,19 @@ class SessionChannel < ApplicationCable::Channel
   end
 
   # Builds the system prompt payload for debug mode transmission.
+  # Delegates to {Session.system_prompt_payload} for the shared format.
+  # Includes deterministic tool schemas (standard + spawn tools).
+  # MCP tools appear after the first LLM request via live broadcast.
   # @param session [Session]
   # @return [Hash, nil] the system prompt payload, or nil if no prompt
   def system_prompt_payload(session)
     prompt = session.system_prompt
     return unless prompt
 
-    tokens = [(prompt.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
-    {
-      "type" => "system_prompt",
-      "rendered" => {
-        "debug" => {role: :system_prompt, content: prompt, tokens: tokens, estimated: true}
-      }
-    }
+    Session.system_prompt_payload(prompt, tools: session.tool_schemas)
   end
 
-  # Merges the Anthropic subscription token into encrypted credentials,
-  # preserving existing keys (e.g. secret_key_base).
+  # Writes the Anthropic subscription token to encrypted storage.
   #
   # @param token [String] validated Anthropic subscription token
   # @return [void]

data/app/decorators/agent_message_decorator.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-# Decorates agent_message events for display in the TUI.
+# Decorates agent_message records for display in the TUI.
 # Basic mode returns role and content. Verbose mode adds a timestamp.
 # Debug mode adds token count (exact when counted, estimated when not).
-class AgentMessageDecorator < EventDecorator
+class AgentMessageDecorator < MessageDecorator
   # @return [Hash] structured agent message data
   #   `{role: :assistant, content: String}`
   def render_basic