anima-core 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8a12f6624492adc6c4de4e5fbc5e28df74edf73a568b73fc0819a8d3fc45163
-  data.tar.gz: 84f3c8680deb81a5e4989abd7b9eeafaae9bdc8e5b0a04db6af27c615f31144c
+  metadata.gz: 283cb2ad728734b96a5badc8b6fc2624c920d3dbefd17412bf5c5f4ae452d6e3
+  data.tar.gz: 0ecef454ffd58b1a4c232338e58a4d20fe4b42f4c3d2ecd6aca6dcc446b0daed
 SHA512:
-  metadata.gz: ae5c8c7ba47910544c6bb3b316bed1a90a54929cae275983c8dd36fca91cdceebbd06cd50b6a1e512d1142e38ab8ebc414b635dd0ed0ff67eea74c5e0af86d86
-  data.tar.gz: 8d8c6ddf84970520c805da2b2fb98d6b2c47faad068f5e602e89389bcc7e70bd206a0ed35dc7dc94aeef2bb8cea615e57627fcf883937d23ad2f70f5610bd6e2
+  metadata.gz: 69115665f072f86b590222cdf4c6ec3ca75be2287fea4d1b50b2361525cb31b75e561b6f6e0ae0e375dfa7c5717b6d549237202f76a7dd4a64826c19a26311fe
+  data.tar.gz: b7b35426013e036bc18c5bd8906f26cadd360be8246ef213018deea41cac52e04747a321c6aaf5835dc9f04ff6c19f04bd344de97c08227591bf6563e03abab1

data/.reek.yml

@@ -13,8 +13,8 @@ detectors:
   NilCheck:
     exclude:
       - "Anima::Settings#get"
+      - "TUI::Settings#get"
   # Rescue blocks naturally reference the error object more than self.
-  # EnvironmentProbe assembles output from local data structures — not envy.
   # Brain transcript builds from event collection — the method's entire purpose.
   # ConfigMigrator text processing methods naturally reference local line arrays.
   # ToolDecorator subclasses operate on the tool result — that's the pattern.
@@ -22,7 +22,6 @@ detectors:
   FeatureEnvy:
     exclude:
       - "AnalyticalBrainJob#perform"
-      - "EnvironmentProbe"
       - "AnalyticalBrain::Runner#build_messages"
       - "Anima::ConfigMigrator"
       - "WebGetToolDecorator"
@@ -35,8 +34,11 @@ 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.
@@ -65,13 +67,13 @@ detectors:
       - "WebGetToolDecorator#text_html"
   # Session model is the core domain object — methods grow naturally.
   # Mcp CLI accumulates subcommand helpers across add/remove/list/secrets.
-  # EnvironmentProbe probes multiple orthogonal facets (OS, Git, project files).
-  # Each facet needs its own detection + formatting methods.
+  # ShellSession probes multiple orthogonal facets (CWD, Git, project files)
+  # and manages PTY lifecycle — methods grow with responsibilities.
   TooManyMethods:
     exclude:
       - "Session"
       - "Anima::CLI::Mcp"
-      - "EnvironmentProbe"
+      - "ShellSession"
       # Runner composes system prompt from modular sections — methods grow with responsibilities.
       - "AnalyticalBrain::Runner"
   # Decorators branch on tool type across 4 render modes — inherent to the pattern.
@@ -83,15 +85,19 @@ detectors:
       # Runner checks session type to compose responsibilities — the core dispatch.
       - "AnalyticalBrain::Runner"
   # EventDecorator holds shared rendering constants (icons, markers, dispatch maps).
-  # Event model holds domain type constants (TYPES, CONTEXT_TYPES, SPAWN_TOOLS, etc.).
+  # Message holds domain type constants (TYPES, CONTEXT_TYPES, LLM_TYPES, etc.).
   TooManyConstants:
     exclude:
       - "EventDecorator"
-      - "Event"
+      - "Message"
   # encode_utf8 is descriptive — the digit triggers a false positive.
   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

@@ -14,7 +14,7 @@ Anima is different. It's built on the premise that if you want an agent — a re
 
 **Memory that works like memory.** Other systems bolt on memory as an afterthought — filing cabinets the agent has to consciously open mid-task. It never does; the truck is already moving. Anima's memory department ([Mneme](#semantic-memory-mneme)) runs as a third brain process on the event bus. It summarizes what's about to leave the viewport. It compresses short-term into long-term, like biological memory consolidating during sleep. It pins critical moments to active goals so exact instructions survive where summaries would lose nuance. And it recalls — automatically, passively — surfacing relevant older memories right after the soul, right before the present. The agent doesn't decide to remember. It just remembers.
 
-**Sub-agents that already know everything.** When Anima spawns a sub-agent, it inherits the parent's full event stream — every file read, every decision, every user message. No "let me summarize what I know." Lossless context. Zero wasted tool calls on rediscovery.
+**Sub-agents that know who they are.** When Anima spawns a sub-agent, it starts clean — identity, task, and nothing else. No inherited conversation history means the sub-agent works on its task, not the parent's trajectory. Context flows through explicit messages, not leaked assistant turns.
 
 **A soul the agent writes itself.** Anima's first session is birth. The agent wakes up, explores its world, meets its human, and writes its own identity. Not a personality description in a config file — a living document the agent authors and evolves. Always in context, always its own.
 
@@ -63,7 +63,7 @@ Anima (Ruby, Rails 8.1 headless)
 ├── Skills       — domain knowledge bundles (Markdown, user-extensible)
 ├── Workflows    — operational recipes for multi-step tasks
 ├── MCP          — external tool integration (Model Context Protocol)
-├── Sub-agents   — autonomous child sessions with lossless context inheritance
+├── Sub-agents   — autonomous child sessions with isolated context
 ├── Mneme        — memory department (summarization, compression, pinning, recall)
 │
 │ Designed:
@@ -129,10 +129,11 @@ State directory (`~/.anima/`):
 ```
 ~/.anima/
 ├── soul.md          # Agent's self-authored identity (always in context)
-├── config.toml      # Main settings (hot-reloadable)
+├── config.toml      # Brain settings (hot-reloadable)
+├── tui.toml         # TUI 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)
@@ -141,7 +142,7 @@ State directory (`~/.anima/`):
 └── tmp/
 ```
 
-Updates: `anima update` — upgrades the gem, merges new config settings into your existing `config.toml` without overwriting customized values, and restarts the systemd service if it's running. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
+Updates: `anima update` — upgrades the gem, merges new config settings into both `config.toml` and `tui.toml` without overwriting customized values, and restarts the systemd service if it's running. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
 
 ### Authentication Setup
 
@@ -149,7 +150,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,18 +163,23 @@ 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`.
 
 ### Sub-Agents
 
-Sub-agents aren't processes — they're sessions on the same event bus. When a sub-agent spawns, its viewport assembles from two scopes: its own events (prioritized) and the parent's events (filling remaining budget). No context serialization, no summary prompts — the sub-agent sees the parent's raw event stream and already knows everything the parent knows. Lossless inheritance by architecture, not by prompting.
+Sub-agents aren't processes — they're sessions on the same event bus. When a sub-agent spawns, it starts with a clean context: a system prompt (identity + communication instructions), a Goal from the task description, and a single user message containing the task — auto-pinned so it survives viewport eviction. No parent conversation history. Sub-agents inherit the parent shell's working directory at spawn time and use a separate model and token budget (configurable via `subagent_model` and `subagent_token_budget`).
 
 Two types:
 
@@ -189,22 +195,25 @@ 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** from its task description and a pinned user message containing the task text. 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
 
-Domain knowledge bundles loaded from Markdown files. Skills provide specialized expertise that the analytical brain activates and deactivates based on conversation context.
+Domain knowledge bundles loaded from Markdown files. Skills provide specialized expertise that the analytical brain activates based on conversation context. Skill content enters the conversation as phantom tool_use/tool_result pairs through the `PendingMessage` promotion flow — the same mechanism used for sub-agent messages. This keeps the system prompt stable for prompt caching while skills flow through the sliding window like regular messages.
 
 - **Built-in skills:** ActiveRecord, Draper decorators, DragonRuby, MCP server, RatatuiRuby, RSpec, GitHub issues
 - **User skills:** Drop `.md` files into `~/.anima/skills/` to add custom knowledge
 - **Override:** User skills with the same name replace built-in ones
 - **Format:** Flat files (`skill-name.md`) or directories (`skill-name/SKILL.md` with `examples/` and `references/`)
+- **Viewport deduplication:** The brain's skill catalog excludes skills already visible in the viewport, preventing redundant activation
 
 Active skills are displayed in the TUI HUD panel (toggle with `C-a → h`).
 
 ### Workflows
 
-Operational recipes that describe multi-step tasks. Unlike skills (domain knowledge), workflows describe WHAT to do. The analytical brain activates a workflow when it recognizes a matching task, converts the prose into tracked goals, and deactivates it when done.
+Operational recipes that describe multi-step tasks. Unlike skills (domain knowledge), workflows describe WHAT to do. The analytical brain activates a workflow when it recognizes a matching task, converts the prose into tracked goals, and deactivates it when done. Like skills, workflow content enters the conversation as phantom tool pairs through the same `PendingMessage` flow.
 
 - **Built-in workflows:** `feature`, `commit`, `create_plan`, `implement_plan`, `review_pr`, `create_note`, `research_codebase`, `decompose_ticket`, and more
 - **User workflows:** Drop `.md` files into `~/.anima/workflows/` to add custom workflows
@@ -255,12 +264,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 +279,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.
@@ -279,7 +288,9 @@ Goals form a two-level hierarchy (root goals with sub-goals) and are displayed i
 
 ### Configuration
 
-All tunable values are exposed through `~/.anima/config.toml` with hot-reload (no restart needed):
+Brain and TUI have separate config files — both hot-reloadable (no restart needed).
+
+**Brain settings** (`~/.anima/config.toml`):
 
 ```toml
 [llm]
@@ -287,7 +298,9 @@ model = "claude-opus-4-6"
 fast_model = "claude-haiku-4-5"
 max_tokens = 8192
 max_tool_rounds = 250
-token_budget = 190_000
+token_budget = 120_000
+subagent_model = "claude-sonnet-4-6"
+subagent_token_budget = 90_000
 
 [timeouts]
 api = 300
@@ -296,13 +309,34 @@ command = 30
 [analytical_brain]
 max_tokens = 4096
 blocking_on_user_message = true
-event_window = 20
+message_window = 20
 
 [session]
 default_view_mode = "basic"
 name_generation_interval = 30
 ```
 
+**TUI settings** (`~/.anima/tui.toml`):
+
+```toml
+[connection]
+default_host = "localhost:42134"    # Override per-launch with --host
+
+[chat]
+scroll_step = 1
+viewport_back_buffer = 3
+
+[theme]
+rate_limit_warning = 70             # Yellow at 70%
+rate_limit_critical = 90            # Red at 90%
+user_message_bg = 22                # 256-color: dark green
+assistant_message_bg = 17           # 256-color: dark navy
+scrollbar_thumb = "cyan"
+border_focused = "yellow"
+```
+
+The TUI is a standalone client with zero Rails dependency. Its settings cover connection tuning, scroll behavior, terminal watchdog, theme colors, and performance logging. See `~/.anima/tui.toml` for all available options.
+
 ## Design
 
 ### Three Layers (mirroring biology)
@@ -331,7 +365,7 @@ Events flow through two channels:
 1. **In-process** — Rails Structured Event Reporter (local subscribers like Persister)
 2. **Over the wire** — Action Cable WebSocket (`Event::Broadcasting` callbacks push to connected TUI clients)
 
-Events fire, subscribers react, state updates. The system prompt — soul, active skills, active workflow, current goals — is assembled fresh for each LLM call from live state, not from the event stream. The agent's identity (soul.md) and capabilities (skills, workflows) are always current, never stale.
+Events fire, subscribers react, state updates. The system prompt — soul and current goals — is assembled fresh for each LLM call from live state, not from the event stream. Skills and workflows flow through the message stream as phantom tool pairs, keeping the system prompt stable for prompt caching. The agent's identity (soul.md) is always current, never stale.
 
 ### Context as Viewport, Not Tape
 
@@ -341,7 +375,7 @@ The viewport is a live query, not a log. It walks events newest-first until the
 
 This means sessions are endless. No compaction. No lossy rewriting. The model always operates in fresh, high-quality context. The [dumb zone](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) never arrives. Meanwhile, Mneme runs as a background department — summarizing evicted events into persistent snapshots so past context is preserved, not destroyed.
 
-Sub-agent viewports compose from two event scopes — their own events (prioritized) and parent events (filling remaining budget). Same mechanism, no special handling. The bus is the architecture.
+Sub-agent viewports use the same mechanism — their own events only, no parent context inheritance. The parent provides context through the task description, and the sub-agent builds its own conversation from a clean slate.
 
 ### Brain as Microservices on a Shared Event Bus
 
@@ -396,6 +430,45 @@ 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).
+
+**Token Economy HUD**: A fixed panel at the bottom of the HUD displays API economics extracted from every Anthropic response:
+
+```
+╭ 📊 Token Economy ────────────────────╮
+│  5h ░░░░░░░░  1% ➞3h42m              │
+│  7d ▓▓▓▓▓▓▓▓ 98%                     │
+│  ⚡ ▓▓▓▓▓▓░░ 69%                     │
+│  💾 6.3K tokens                      │
+│     ⠛⣿⣷⣶⣿⣿⣿⣿⣷⣶⣿⣿⣿           │
+│  🟢 Verbose                          │
+╰──────────────────────────────────────╯
+```
+
+| Row | Description |
+|-----|-------------|
+| `5h` | 5-hour rate limit utilization with progress bar and reset countdown |
+| `7d` | 7-day rate limit utilization with progress bar |
+| `⚡` | Cache hit rate — percentage of input tokens served from cache |
+| `💾` | Cumulative tokens saved by cache hits |
+| `⠛⣿` | Braille sparkline — per-call cache hit history (2 calls per character); drops signal cache busts |
+| `🟢` | Connection status and current view mode |
+
+Progress bars are color-coded: green (< 70%), yellow (70-89%), red (>= 90%) for rate limits; inverted for cache hits (green >= 70%, red < 30%). All data comes from Anthropic API response headers and usage objects, broadcast as message metadata via ActionCable.
+
+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,9 +655,9 @@ 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)
+- Sub-agents with isolated context (5 specialists + generic)
 - Client-server architecture with WebSocket transport + graceful reconnection
 - Collapsible HUD panel with goals, skills, workflow, and sub-agent tracking
 - Three TUI view modes (Basic / Verbose / Debug)

data/agents/codebase-analyzer.md

@@ -1,7 +1,7 @@
 ---
 name: codebase-analyzer
 description: Traces data flow and explains how code works. Returns file:line references.
-tools: read, bash
+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 to model after. Returns concrete code examples.
-tools: read, bash
+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 official docs. Returns ready-to-use code examples.
-tools: web_get, read
+tools: web_get, read_file
 color: cyan
 ---
 

data/agents/thoughts-analyzer.md

@@ -1,7 +1,7 @@
 ---
 name: thoughts-analyzer
 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, bash
+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: Researches topics across multiple web sources. Use when a single page won't answer the question.
-tools: web_get, bash, read
+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

@@ -47,8 +47,8 @@ class SessionChannel < ApplicationCable::Channel
   # 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 message 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 "message_id" (positive integer)
+  # @param data [Hash] must include "pending_message_id" (positive integer)
   def recall_pending(data)
-    message_id = data["message_id"].to_i
-    return if message_id <= 0
-
-    message = Message.find_by(
-      id: message_id,
-      session_id: @current_session_id,
-      message_type: "user_message",
-      status: Message::PENDING_STATUS
-    )
-    return unless message
-
-    message.destroy!
-    ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "message_id" => message_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.
@@ -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)
@@ -217,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)
@@ -251,6 +258,7 @@ class SessionChannel < ApplicationCable::Channel
   # 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 message broadcasts can compute
   # eviction diffs accurately.
@@ -262,11 +270,16 @@ class SessionChannel < ApplicationCable::Channel
     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 message broadcasts can compute
   # eviction diffs accurately.
@@ -279,12 +292,21 @@ class SessionChannel < ApplicationCable::Channel
     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 message 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 message [Message] the persisted message record
@@ -294,7 +316,7 @@ class SessionChannel < ApplicationCable::Channel
     viewport = session.viewport_messages
     session.snapshot_viewport!(viewport.map(&:id))
 
-    viewport.each do |msg|
+    viewport.reverse_each do |msg|
       yield msg, decorate_message_payload(msg, session.view_mode)
     end
   end
@@ -338,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 / Message::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/tool_call_decorator.rb

@@ -7,7 +7,7 @@ require "toon"
 # aggregated tool counter instead. Verbose mode returns tool name
 # and a formatted preview of the input arguments. Debug mode shows
 # full untruncated input with tool_use_id — TOON format for most
-# tools, but write tool content preserves actual newlines.
+# tools, but write_file tool content preserves actual newlines.
 #
 # Think tool calls are special: "aloud" thoughts are shown in all
 # view modes (with a thought bubble), while "inner" thoughts are
@@ -97,18 +97,18 @@ class ToolCallDecorator < MessageDecorator
   def format_debug_input
     input = tool_input
     case payload["tool_name"]
-    when "write" then format_write_content(input)
+    when "write_file" then format_write_content(input)
     else Toon.encode(input)
     end
   end
 
   # Formats write tool input with file path header and content body.
   # Content newlines are preserved so the TUI can render them as
-  # separate lines, matching how read tool responses display file content.
-  # @param input [Hash] tool input hash with "file_path" and "content" keys
+  # separate lines, matching how read_file tool responses display file content.
+  # @param input [Hash] tool input hash with "path" and "content" keys
   # @return [String] path + content with real newlines, or TOON-encoded hash when content is empty
   def format_write_content(input)
-    path = input.dig("file_path").to_s
+    path = input.dig("path").to_s
     content = input.dig("content").to_s
     return Toon.encode(input) if content.empty?
 
@@ -125,8 +125,8 @@ class ToolCallDecorator < MessageDecorator
       "$ #{input&.dig("command")}"
     when "web_get"
       "GET #{input&.dig("url")}"
-    when "read", "edit", "write"
-      input&.dig("file_path").to_s
+    when "read_file", "edit_file", "write_file"
+      input&.dig("path").to_s
     else
       truncate_lines(Toon.encode(input), max_lines: 2)
     end