anima-core 1.2.0 → 1.4.0

data/db/structure.sql

@@ -0,0 +1,120 @@
+CREATE TABLE IF NOT EXISTS "schema_migrations" ("version" varchar NOT NULL PRIMARY KEY);
+CREATE TABLE IF NOT EXISTS "ar_internal_metadata" ("key" varchar NOT NULL PRIMARY KEY, "value" varchar, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL);
+CREATE TABLE IF NOT EXISTS "goals" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "session_id" integer NOT NULL, "parent_goal_id" integer, "description" text NOT NULL, "status" varchar DEFAULT 'active' NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL, "completed_at" datetime(6), "evicted_at" datetime(6), CONSTRAINT "fk_rails_874b7534ae"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+, CONSTRAINT "fk_rails_feeb9df31e"
+FOREIGN KEY ("parent_goal_id")
+  REFERENCES "goals" ("id")
+);
+CREATE INDEX "index_goals_on_session_id" ON "goals" ("session_id");
+CREATE INDEX "index_goals_on_parent_goal_id" ON "goals" ("parent_goal_id");
+CREATE INDEX "index_goals_on_session_id_and_status" ON "goals" ("session_id", "status");
+CREATE TABLE IF NOT EXISTS "messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "session_id" integer NOT NULL, "message_type" varchar NOT NULL, "payload" json DEFAULT '{}' NOT NULL, "timestamp" integer(8) NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL, "token_count" integer DEFAULT 0 NOT NULL, "tool_use_id" varchar, "status" varchar, "api_metrics" json, CONSTRAINT "fk_rails_1ee2a92df0"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_messages_on_session_id_and_status" ON "messages" ("session_id", "status");
+CREATE INDEX "index_messages_on_tool_use_id" ON "messages" ("tool_use_id");
+CREATE INDEX "index_messages_on_session_id" ON "messages" ("session_id");
+CREATE INDEX "index_messages_on_message_type" ON "messages" ("message_type");
+CREATE INDEX "index_messages_on_session_id_and_message_type" ON "messages" ("session_id", "message_type");
+CREATE TABLE IF NOT EXISTS "pinned_messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "message_id" integer NOT NULL, "display_text" text NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_4a5f237c43"
+FOREIGN KEY ("message_id")
+  REFERENCES "messages" ("id")
+);
+CREATE UNIQUE INDEX "index_pinned_messages_on_message_id" ON "pinned_messages" ("message_id");
+CREATE TABLE IF NOT EXISTS "goal_pinned_messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "goal_id" integer NOT NULL, "pinned_message_id" integer NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_fb51bfeebe"
+FOREIGN KEY ("pinned_message_id")
+  REFERENCES "pinned_messages" ("id")
+, CONSTRAINT "fk_rails_689fd4bf8a"
+FOREIGN KEY ("goal_id")
+  REFERENCES "goals" ("id")
+);
+CREATE INDEX "index_goal_pinned_messages_on_goal_id" ON "goal_pinned_messages" ("goal_id");
+CREATE INDEX "index_goal_pinned_messages_on_pinned_message_id" ON "goal_pinned_messages" ("pinned_message_id");
+CREATE UNIQUE INDEX "index_goal_pinned_messages_on_goal_id_and_pinned_message_id" ON "goal_pinned_messages" ("goal_id", "pinned_message_id");
+CREATE TABLE IF NOT EXISTS "snapshots" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "session_id" integer NOT NULL, "text" text NOT NULL, "from_message_id" integer NOT NULL, "to_message_id" integer NOT NULL, "level" integer DEFAULT 1 NOT NULL, "token_count" integer DEFAULT 0 NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_eb2ad51db9"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_snapshots_on_session_id" ON "snapshots" ("session_id");
+CREATE INDEX "index_snapshots_on_session_id_and_level" ON "snapshots" ("session_id", "level");
+CREATE INDEX "index_snapshots_on_session_and_event_range" ON "snapshots" ("session_id", "from_message_id", "to_message_id");
+CREATE VIRTUAL TABLE messages_fts USING fts5(
+  searchable_text,
+  content='',
+  contentless_delete=1,
+  tokenize='porter unicode61'
+)
+/* messages_fts(searchable_text) */;
+CREATE TABLE IF NOT EXISTS 'messages_fts_data'(id INTEGER PRIMARY KEY, block BLOB);
+CREATE TABLE IF NOT EXISTS 'messages_fts_idx'(segid, term, pgno, PRIMARY KEY(segid, term)) WITHOUT ROWID;
+CREATE TABLE IF NOT EXISTS 'messages_fts_docsize'(id INTEGER PRIMARY KEY, sz BLOB, origin INTEGER);
+CREATE TABLE IF NOT EXISTS 'messages_fts_config'(k PRIMARY KEY, v) WITHOUT ROWID;
+CREATE TRIGGER messages_fts_insert AFTER INSERT ON messages
+WHEN NEW.message_type IN ('user_message', 'agent_message', 'system_message')
+  OR (NEW.message_type = 'tool_call' AND json_extract(NEW.payload, '$.tool_name') = 'think')
+BEGIN
+  INSERT INTO messages_fts(rowid, searchable_text)
+  VALUES (
+    NEW.id,
+    CASE
+      WHEN NEW.message_type IN ('user_message', 'agent_message', 'system_message')
+        THEN json_extract(NEW.payload, '$.content')
+      WHEN NEW.message_type = 'tool_call'
+        THEN json_extract(NEW.payload, '$.tool_input.thoughts')
+    END
+  );
+END;
+CREATE TRIGGER messages_fts_delete AFTER DELETE ON messages
+WHEN OLD.message_type IN ('user_message', 'agent_message', 'system_message')
+  OR (OLD.message_type = 'tool_call' AND json_extract(OLD.payload, '$.tool_name') = 'think')
+BEGIN
+  DELETE FROM messages_fts WHERE rowid = OLD.id;
+END;
+CREATE TABLE IF NOT EXISTS "secrets" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "namespace" varchar NOT NULL, "key" varchar NOT NULL, "value" text NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL);
+CREATE UNIQUE INDEX "index_secrets_on_namespace_and_key" ON "secrets" ("namespace", "key");
+CREATE INDEX "index_goals_on_evicted_at" ON "goals" ("evicted_at");
+CREATE TABLE IF NOT EXISTS "pending_messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "session_id" integer NOT NULL, "content" text NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL, "source_type" varchar DEFAULT 'user' NOT NULL, "source_name" varchar, CONSTRAINT "fk_rails_007242365b"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_pending_messages_on_session_id" ON "pending_messages" ("session_id");
+CREATE TABLE IF NOT EXISTS "sessions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL, "view_mode" varchar DEFAULT 'basic' NOT NULL, "processing" boolean DEFAULT FALSE NOT NULL, "parent_session_id" integer, "prompt" text, "granted_tools" text, "name" varchar, "viewport_message_ids" json DEFAULT '[]' NOT NULL, "active_skills" json DEFAULT '[]' NOT NULL, "active_workflow" varchar, "interrupt_requested" boolean DEFAULT FALSE NOT NULL, "mneme_boundary_message_id" integer, "mneme_snapshot_first_message_id" integer, "mneme_snapshot_last_message_id" integer, "initial_cwd" varchar, CONSTRAINT "fk_rails_045409ac27"
+FOREIGN KEY ("parent_session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_sessions_on_parent_session_id" ON "sessions" ("parent_session_id");
+INSERT INTO "schema_migrations" (version) VALUES
+('20260403080031'),
+('20260401210935'),
+('20260401180000'),
+('20260330120000'),
+('20260329120000'),
+('20260328152142'),
+('20260328100000'),
+('20260326180000'),
+('20260321140100'),
+('20260321140000'),
+('20260321120000'),
+('20260321080000'),
+('20260316094817'),
+('20260315191105'),
+('20260315144837'),
+('20260315140843'),
+('20260315100000'),
+('20260314150000'),
+('20260314140000'),
+('20260314112417'),
+('20260314075248'),
+('20260313020000'),
+('20260313010000'),
+('20260312170000'),
+('20260308160000'),
+('20260308150000'),
+('20260308140000'),
+('20260308130000'),
+('20260308124203'),
+('20260308124202');
+

data/lib/agent_loop.rb

@@ -1,27 +1,24 @@
 # frozen_string_literal: true
 
+require "shellwords"
+
 # Orchestrates the LLM agent loop: accepts user input, runs the tool-use
 # cycle via {LLM::Client}, and emits events through {Events::Bus}.
 #
 # Extracted from {TUI::Screens::Chat} so the same agent logic can run from
 # the TUI, a background job, or an Action Cable channel.
 #
-# @note Not thread-safe. Callers must serialize concurrent calls to {#process}
-#   (e.g. TUI uses a loading flag, future callers should use session-level locks).
+# @note Not thread-safe. Callers must serialize concurrent access
+#   (e.g. {AgentRequestJob} uses session-level processing locks).
 #
 # @example Basic usage
 #   loop = AgentLoop.new(session: session)
-#   loop.process("What files are in the current directory?")
+#   loop.run
 #   loop.finalize
 #
 # @example With dependency injection (testing)
 #   loop = AgentLoop.new(session: session, client: mock_client, registry: mock_registry)
-#   loop.process("hello")
-#
-# @example Background job usage (retry-safe)
-#   loop = AgentLoop.new(session: session)
-#   loop.run  # processes persisted session messages without emitting UserMessage
-#   loop.finalize
+#   loop.run
 class AgentLoop
   # @return [Session] the conversation session this loop operates on
   attr_reader :session
@@ -30,38 +27,17 @@ class AgentLoop
   # @param shell_session [ShellSession, nil] injectable persistent shell;
   #   created automatically if not provided
   # @param client [LLM::Client, nil] injectable LLM client;
-  #   created lazily on first {#process} call if not provided
+  #   created lazily on first {#run} call if not provided
   # @param registry [Tools::Registry, nil] injectable tool registry;
-  #   built lazily on first {#process} call if not provided
+  #   built lazily on first {#run} call if not provided
   def initialize(session:, shell_session: nil, client: nil, registry: nil)
     @session = session
     @shell_session = shell_session || ShellSession.new(session_id: session.id)
+    restore_initial_cwd
     @client = client
     @registry = registry
   end
 
-  # Runs the agent loop for a single user input.
-  #
-  # Persists the user message directly (the global Persister skips
-  # non-pending user messages because {AgentRequestJob} owns their
-  # lifecycle). Then emits a bus notification and delegates to {#run}.
-  # On error emits {Events::AgentMessage} with the error text.
-  #
-  # @param input [String] raw user input
-  # @return [String, nil] the agent's response text, or nil for blank input
-  def process(input)
-    text = input.to_s.strip
-    return if text.empty?
-
-    persist_user_message(text)
-    Events::Bus.emit(Events::UserMessage.new(content: text, session_id: @session.id))
-    run
-  rescue => error
-    error_message = "#{error.class}: #{error.message}"
-    Events::Bus.emit(Events::AgentMessage.new(content: error_message, session_id: @session.id))
-    error_message
-  end
-
   # Makes the first LLM API call to verify delivery. Called inside the
   # Bounce Back transaction — if this raises, the user event rolls back.
   #
@@ -71,7 +47,7 @@ class AgentLoop
   # @return [void]
   # @raise [Providers::Anthropic::Error] on any LLM delivery failure
   def deliver!
-    @client ||= LLM::Client.new
+    @client ||= build_client
     @registry ||= build_tool_registry
 
     messages = @session.messages_for_llm
@@ -82,6 +58,7 @@ class AgentLoop
       messages: messages,
       max_tokens: @client.max_tokens,
       tools: @registry.schemas,
+      include_metrics: true,
       **options
     )
   end
@@ -100,7 +77,7 @@ class AgentLoop
   # @raise [Providers::Anthropic::TransientError] on retryable network/server errors
   # @raise [Providers::Anthropic::AuthenticationError] on auth failures
   def run
-    @client ||= LLM::Client.new
+    @client ||= build_client
     @registry ||= build_tool_registry
 
     messages = @session.messages_for_llm
@@ -109,14 +86,20 @@ class AgentLoop
     first_resp = @first_response
     @first_response = nil
 
-    response = @client.chat_with_tools(
+    between_rounds = -> { @session.promote_pending_messages! }
+
+    result = @client.chat_with_tools(
       messages, registry: @registry, session_id: @session.id,
-      first_response: first_resp, **options
+      first_response: first_resp, between_rounds: between_rounds, **options
     )
-    return unless response
-
-    Events::Bus.emit(Events::AgentMessage.new(content: response, session_id: @session.id))
-    response
+    return unless result
+
+    Events::Bus.emit(Events::AgentMessage.new(
+      content: result[:text],
+      session_id: @session.id,
+      api_metrics: result[:api_metrics]
+    ))
+    result[:text]
   end
 
   # Clean up the underlying {ShellSession} PTY and resources.
@@ -127,7 +110,7 @@ class AgentLoop
 
   # Tool classes available to all sessions by default.
   # @return [Array<Class<Tools::Base>>]
-  STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::Remember].freeze
+  STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::Remember, Tools::Recall].freeze
 
   # Tools that bypass {Session#granted_tools} filtering.
   # The agent's reasoning depends on these regardless of task scope.
@@ -140,20 +123,37 @@ class AgentLoop
 
   private
 
-  # @see Session#create_user_message
-  def persist_user_message(content)
-    @session.create_user_message(content)
+  # Restores the working directory inherited from the parent session.
+  # Sub-agents store the parent's CWD at spawn time so their shell starts
+  # in the same directory the parent was working in.
+  # @return [void]
+  def restore_initial_cwd
+    cwd = @session.initial_cwd
+    return unless cwd.present? && File.directory?(cwd)
+
+    @shell_session.run("cd #{Shellwords.shellescape(cwd)}")
   end
 
-  # Assembles LLM options (system prompt, environment context).
+  # Builds the LLM client with the appropriate model for this session type.
+  # Sub-agents use a separate (typically cheaper) model from Settings.
+  # @return [LLM::Client]
+  def build_client
+    if @session.sub_agent?
+      LLM::Client.new(model: Anima::Settings.subagent_model)
+    else
+      LLM::Client.new
+    end
+  end
+
+  # Assembles LLM options (system prompt).
+  # Broadcasts the full debug context (system prompt + tool schemas)
+  # to debug-mode TUI clients on every LLM request.
   # @return [Hash] options for {LLM::Client#chat_with_tools}
   def build_llm_options
     options = {}
-    unless @session.sub_agent?
-      env_context = EnvironmentProbe.to_prompt(@shell_session.pwd)
-    end
-    prompt = @session.system_prompt(environment_context: env_context)
+    prompt = @session.system_prompt
     options[:system] = prompt if prompt
+    @session.broadcast_debug_context(system: prompt, tools: @registry&.schemas)
     options
   end
 
@@ -172,7 +172,9 @@ class AgentLoop
 
     granted_standard_tools.each { |tool| registry.register(tool) }
 
-    unless @session.sub_agent?
+    if @session.sub_agent?
+      registry.register(Tools::MarkGoalCompleted)
+    else
       registry.register(Tools::SpawnSubagent)
       registry.register(Tools::SpawnSpecialist)
       registry.register(Tools::OpenIssue)

data/lib/agents/definition.rb

@@ -12,7 +12,7 @@ module Agents
   #   ---
   #   name: codebase-analyzer
   #   description: Analyzes codebase implementation details.
-  #   tools: read, bash
+  #   tools: read_file, bash
   #   model: claude-sonnet-4-5
   #   ---
   #

data/lib/analytical_brain/runner.rb

@@ -9,7 +9,9 @@ module AnalyticalBrain
   # active depends on the session type:
   #
   # * **Parent sessions** — session naming, skill/workflow/goal management
-  # * **Child sessions** — sub-agent nickname assignment, skill/workflow/goal management
+  # * **Child sessions** — sub-agent nickname assignment, skill management
+  #   (goal tracking and workflows disabled — sub-agents manage their sole goal
+  #   via mark_goal_completed)
   #
   # Tools mutate the observed session directly (e.g. renaming it, activating
   # skills), but no trace of the brain's reasoning is persisted — events are
@@ -51,7 +53,8 @@ module AnalyticalBrain
           ──────────────────────────────
           SKILL MANAGEMENT
           ──────────────────────────────
-          Activate skills when the conversation enters their domain.
+          Activate skills when the conversation signals intent — before the agent acts on it.
+          Late activation means the agent works without domain knowledge.
           Deactivate when the agent moves to a different domain.
           Multiple skills can be active at once.
         PROMPT
@@ -104,7 +107,7 @@ module AnalyticalBrain
 
     # Which responsibilities activate for each session type.
     PARENT_RESPONSIBILITIES = %i[session_naming skill_management workflow_management goal_tracking].freeze
-    CHILD_RESPONSIBILITIES = %i[sub_agent_naming skill_management workflow_management goal_tracking].freeze
+    CHILD_RESPONSIBILITIES = %i[sub_agent_naming skill_management].freeze
 
     # @param session [Session] the session to observe and maintain
     # @param client [LLM::Client, nil] injectable LLM client (defaults to fast model)
@@ -201,7 +204,7 @@ module AnalyticalBrain
         #{transcript}
         ```
 
-        Assign a nickname, activate relevant skills, then call everything_is_ready.
+        Assign a nickname and activate relevant skills, then call everything_is_ready.
       MSG
       [{role: "user", content: content}]
     end
@@ -269,9 +272,15 @@ module AnalyticalBrain
       SECTION
     end
 
+    # Skills already visible in the viewport are excluded from the catalog
+    # so the brain doesn't re-activate them. When a skill evicts from the
+    # viewport, it reappears here and the brain can re-inject if relevant.
+    #
+    # @see Session#skills_in_viewport
     # @return [String] available skills list for the analytical brain
     def skills_catalog_section
-      catalog = Skills::Registry.instance.catalog
+      present = @session.skills_in_viewport
+      catalog = Skills::Registry.instance.catalog.except(*present)
       items = if catalog.empty?
         "None"
       else
@@ -285,9 +294,13 @@ module AnalyticalBrain
       SECTION
     end
 
+    # Workflows already visible in the viewport are excluded from the catalog.
+    #
+    # @see Session#workflow_in_viewport
     # @return [String] available workflows list for the analytical brain
     def workflows_catalog_section
-      catalog = Workflows::Registry.instance.catalog
+      present = @session.workflow_in_viewport
+      catalog = Workflows::Registry.instance.catalog.reject { |name, _| name == present }
       items = if catalog.empty?
         "None"
       else

data/lib/analytical_brain/tools/activate_skill.rb

@@ -3,8 +3,8 @@
 module AnalyticalBrain
   module Tools
     # Activates a domain knowledge skill on the main session.
-    # The skill's content is injected into the main agent's system prompt,
-    # making the knowledge available for the current and future responses.
+    # The skill's content enters the conversation as a phantom
+    # tool_use/tool_result pair through the {PendingMessage} promotion flow.
     class ActivateSkill < ::Tools::Base
       def self.tool_name = "activate_skill"
 

data/lib/analytical_brain/tools/assign_nickname.rb

@@ -47,7 +47,7 @@ module AnalyticalBrain
         return error if error
 
         @session.update!(name: nickname)
-        "Nickname set to @#{nickname}"
+        "Nickname set to #{nickname}"
       end
 
       private

data/lib/analytical_brain/tools/deactivate_skill.rb

@@ -3,7 +3,8 @@
 module AnalyticalBrain
   module Tools
     # Deactivates a domain knowledge skill on the main session.
-    # The skill's content is removed from the main agent's system prompt.
+    # The skill's recalled message stays in the conversation and
+    # evicts naturally from the sliding window.
     class DeactivateSkill < ::Tools::Base
       def self.tool_name = "deactivate_skill"
 

data/lib/analytical_brain/tools/deactivate_workflow.rb

@@ -3,7 +3,8 @@
 module AnalyticalBrain
   module Tools
     # Deactivates the current workflow on the main session.
-    # The workflow's content is removed from the main agent's system prompt.
+    # The workflow's recalled message stays in the conversation and
+    # evicts naturally from the sliding window.
     class DeactivateWorkflow < ::Tools::Base
       def self.tool_name = "deactivate_workflow"
 

data/lib/analytical_brain/tools/finish_goal.rb

@@ -5,6 +5,8 @@ module AnalyticalBrain
     # Marks a goal as completed on the main session. Sets the status to
     # "completed" and records the completion timestamp.
     class FinishGoal < ::Tools::Base
+      include GoalMessaging
+
       def self.tool_name = "finish_goal"
 
       def self.description = "Mark a goal as completed."
@@ -57,6 +59,7 @@ module AnalyticalBrain
 
         msg = "Goal completed: #{desc} (id: #{id})"
         msg += " (released #{released} orphaned pins)" if released > 0
+        enqueue_goal_message(goal, msg)
         msg
       end
     end

data/lib/analytical_brain/tools/goal_messaging.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Shared helper for goal tools that enqueue phantom pair messages
+    # when the analytical brain creates, updates, or completes a goal.
+    #
+    # Including classes must set +@main_session+ to the owning {Session}.
+    module GoalMessaging
+      private
+
+      # Enqueues a goal event as a {PendingMessage} on the main session.
+      # Promoted to a phantom tool_use/tool_result pair so the main agent
+      # sees "I recalled this goal event" in its conversation history.
+      #
+      # @param goal [Goal] the goal that changed
+      # @param confirmation [String] human-readable event description
+      # @return [PendingMessage]
+      def enqueue_goal_message(goal, confirmation)
+        @main_session.pending_messages.create!(
+          content: confirmation,
+          source_type: "goal",
+          source_name: goal.id.to_s
+        )
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/read_workflow.rb

@@ -4,8 +4,8 @@ module AnalyticalBrain
   module Tools
     # Reads and activates a workflow on the main session.
     # Returns the full workflow content so the brain can create goals from it.
-    # Also sets the workflow as active on the session, injecting its content
-    # into the main agent's "Your Expertise" section.
+    # The workflow's content enters the conversation as a phantom
+    # tool_use/tool_result pair through the {PendingMessage} promotion flow.
     class ReadWorkflow < ::Tools::Base
       def self.tool_name = "read_workflow"
 

data/lib/analytical_brain/tools/set_goal.rb

@@ -6,6 +6,8 @@ module AnalyticalBrain
     # objectives (semantic episodes); sub-goals are TODO-style steps within
     # a root goal. The two-level hierarchy is enforced by the Goal model.
     class SetGoal < ::Tools::Base
+      include GoalMessaging
+
       def self.tool_name = "set_goal"
 
       def self.description = "Create a goal or sub-goal."
@@ -40,7 +42,9 @@ module AnalyticalBrain
           description: description,
           parent_goal_id: input["parent_goal_id"]
         )
-        format_confirmation(goal)
+        confirmation = format_confirmation(goal)
+        enqueue_goal_message(goal, confirmation)
+        confirmation
       rescue ActiveRecord::RecordInvalid => error
         {error: error.record.errors.full_messages.join(", ")}
       end

data/lib/analytical_brain/tools/update_goal.rb

@@ -13,6 +13,8 @@ module AnalyticalBrain
     # Completed goals cannot be updated; attempting to do so returns an error
     # so the brain learns to check status before calling this tool.
     class UpdateGoal < ::Tools::Base
+      include GoalMessaging
+
       def self.tool_name = "update_goal"
 
       def self.description = "Refine a goal's wording as understanding evolves."
@@ -49,7 +51,9 @@ module AnalyticalBrain
         return {error: "Cannot update completed goal: #{goal.description} (id: #{goal_id})"} if goal.completed?
 
         goal.update!(description: description)
-        "Goal updated: #{description} (id: #{goal_id})"
+        confirmation = "Goal updated: #{description} (id: #{goal_id})"
+        enqueue_goal_message(goal, confirmation)
+        confirmation
       end
     end
   end

data/lib/anima/cli/mcp/secrets.rb

@@ -5,8 +5,8 @@ require "thor"
 module Anima
   class CLI < Thor
     class Mcp < Thor
-      # CLI commands for managing MCP secrets stored in Rails encrypted
-      # credentials. Secrets are referenced in mcp.toml via
+      # CLI commands for managing MCP secrets stored in the encrypted
+      # secrets table. Secrets are referenced in mcp.toml via
       # +${credential:key_name}+ syntax.
       #
       # @example Store a secret
@@ -22,7 +22,7 @@ module Anima
           true
         end
 
-        desc "set KEY=VALUE", "Store an MCP secret in encrypted credentials"
+        desc "set KEY=VALUE", "Store an MCP secret in encrypted secrets"
         def set(pair)
           key, value = pair.split("=", 2)
           unless value
@@ -50,7 +50,7 @@ module Anima
           keys.each { |key| say "  #{key}" }
         end
 
-        desc "remove KEY", "Remove an MCP secret from encrypted credentials"
+        desc "remove KEY", "Remove an MCP secret from encrypted storage"
         def remove(key)
           secrets = require_mcp_secrets
           unless secrets.list.include?(key)

data/lib/anima/cli/mcp.rb

@@ -12,7 +12,7 @@ module Anima
         true
       end
 
-      desc "secrets SUBCOMMAND", "Manage MCP secrets in encrypted credentials"
+      desc "secrets SUBCOMMAND", "Manage MCP secrets in encrypted storage"
       subcommand "secrets", Secrets
 
       desc "list", "List configured MCP servers with health status"
@@ -40,14 +40,14 @@ module Anima
 
         Use -e KEY=VALUE to set environment variables (stdio servers).
         Use -H "Header: Value" to set HTTP headers (HTTP servers).
-        Use -s KEY=VALUE to store a secret in encrypted credentials.
+        Use -s KEY=VALUE to store a secret in encrypted storage.
       DESC
       option :env, aliases: "-e", type: :string, repeatable: true, banner: "KEY=VALUE",
         desc: "Environment variables (repeatable)"
       option :header, aliases: "-H", type: :string, repeatable: true, banner: "Header: Value",
         desc: "HTTP headers (repeatable)"
       option :secret, aliases: "-s", type: :string, repeatable: true, banner: "KEY=VALUE",
-        desc: "Store secret in encrypted credentials (repeatable)"
+        desc: "Store secret in encrypted storage (repeatable)"
       def add(name, *rest)
         if rest.empty?
           say "Error: missing server URL or command.", :red
@@ -87,7 +87,7 @@ module Anima
         ::Mcp::Config.new
       end
 
-      # Stores secrets from -s KEY=VALUE flags in encrypted credentials.
+      # Stores secrets from -s KEY=VALUE flags in the encrypted secrets table.
       def store_secrets(secret_strings)
         return unless secret_strings&.any?