anima-core 1.1.2 → 1.2.0

data/app/models/snapshot.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 # A persisted summary of conversation context created by Mneme before
-# events evict from the viewport. Snapshots capture the "gist" of what
+# messages evict from the viewport. Snapshots capture the "gist" of what
 # happened so the agent retains awareness of past context.
 #
-# Level 1 snapshots are created from raw events (messages + thinks).
+# Level 1 snapshots are created from raw messages (conversation + thinks).
 # Level 2 snapshots compress multiple Level 1 snapshots (days/weeks scale).
-# Both levels use the same event ID range tracking — an L2 snapshot's range
+# Both levels use the same message ID range tracking — an L2 snapshot's range
 # is the union of its constituent L1 snapshots.
 #
 # @!attribute text
 #   @return [String] the summary text generated by Mneme
-# @!attribute from_event_id
-#   @return [Integer] first event ID covered by this snapshot
-# @!attribute to_event_id
-#   @return [Integer] last event ID covered by this snapshot
+# @!attribute from_message_id
+#   @return [Integer] first message ID covered by this snapshot
+# @!attribute to_message_id
+#   @return [Integer] last message ID covered by this snapshot
 # @!attribute level
-#   @return [Integer] compression level (1 = from raw events, 2 = from L1 snapshots)
+#   @return [Integer] compression level (1 = from raw messages, 2 = from L1 snapshots)
 # @!attribute token_count
 #   @return [Integer] cached token count of the summary text
 class Snapshot < ApplicationRecord
@@ -27,34 +27,34 @@ class Snapshot < ApplicationRecord
   MAX_TEXT_BYTES = 32_768
 
   validates :text, presence: true, length: {maximum: MAX_TEXT_BYTES}
-  validates :from_event_id, presence: true
-  validates :to_event_id, presence: true
+  validates :from_message_id, presence: true
+  validates :to_message_id, presence: true
   validates :level, presence: true, numericality: {greater_than: 0}
   validates :token_count, numericality: {greater_than_or_equal_to: 0}, allow_nil: true
-  validate :from_event_id_not_after_to_event_id
+  validate :from_message_id_not_after_to_message_id
 
   scope :for_level, ->(level) { where(level: level) }
-  scope :chronological, -> { order(:from_event_id) }
+  scope :chronological, -> { order(:from_message_id) }
 
-  # L1 snapshots whose event range is NOT fully contained within any L2 snapshot.
+  # L1 snapshots whose message range is NOT fully contained within any L2 snapshot.
   # Used to determine which L1 snapshots are still "live" in the viewport.
   scope :not_covered_by_l2, -> {
     where.not(
       "EXISTS (SELECT 1 FROM snapshots l2 " \
       "WHERE l2.session_id = snapshots.session_id " \
       "AND l2.level = 2 " \
-      "AND l2.from_event_id <= snapshots.from_event_id " \
-      "AND l2.to_event_id >= snapshots.to_event_id)"
+      "AND l2.from_message_id <= snapshots.from_message_id " \
+      "AND l2.to_message_id >= snapshots.to_message_id)"
     )
   }
 
-  # Snapshots whose source events have fully evicted from the sliding window.
-  # A snapshot is visible when its entire event range precedes the first
-  # event currently in the viewport.
+  # Snapshots whose source messages have fully evicted from the sliding window.
+  # A snapshot is visible when its entire message range precedes the first
+  # message currently in the viewport.
   #
-  # @param first_event_id [Integer] the first event ID in the sliding window
-  scope :source_events_evicted, ->(first_event_id) {
-    where("to_event_id < ?", first_event_id)
+  # @param first_message_id [Integer] the first message ID in the sliding window
+  scope :source_messages_evicted, ->(first_message_id) {
+    where("to_message_id < ?", first_message_id)
   }
 
   # @return [Integer] token cost, using cached count or heuristic estimate
@@ -64,13 +64,13 @@ class Snapshot < ApplicationRecord
 
   private
 
-  def from_event_id_not_after_to_event_id
-    return unless from_event_id && to_event_id
-    errors.add(:from_event_id, "must be <= to_event_id") if from_event_id > to_event_id
+  def from_message_id_not_after_to_message_id
+    return unless from_message_id && to_message_id
+    errors.add(:from_message_id, "must be <= to_message_id") if from_message_id > to_message_id
   end
 
   # @return [Integer] estimated token count (at least 1)
   def estimate_tokens
-    [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+    [(text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
   end
 end

data/db/migrate/20260326180000_rename_event_to_message.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# Renames the persistence layer from Event to Message.
+#
+# Events are ephemeral bus signals; Messages are persisted records of what
+# was said, by whom, in which conversation. The Anthropic API calls them
+# "messages" — this rename aligns the codebase with the agent's vocabulary.
+#
+# See: thoughts/shared/notes/2026-03-24/narrative-design-for-agent-prompts.md
+class RenameEventToMessage < ActiveRecord::Migration[8.1]
+  def up
+    # --- FTS5: drop triggers and virtual table (references old table name) ---
+    execute "DROP TRIGGER IF EXISTS events_fts_insert"
+    execute "DROP TRIGGER IF EXISTS events_fts_delete"
+    execute "DROP TABLE IF EXISTS events_fts"
+
+    # --- Main table: events → messages ---
+    rename_table :events, :messages
+    rename_column :messages, :event_type, :message_type
+
+    # --- Pinned events → pinned messages ---
+    rename_table :pinned_events, :pinned_messages
+    rename_column :pinned_messages, :event_id, :message_id
+
+    # --- Join table: goal_pinned_events → goal_pinned_messages ---
+    rename_table :goal_pinned_events, :goal_pinned_messages
+    rename_column :goal_pinned_messages, :pinned_event_id, :pinned_message_id
+
+    # --- Snapshots: event range columns ---
+    rename_column :snapshots, :from_event_id, :from_message_id
+    rename_column :snapshots, :to_event_id, :to_message_id
+
+    # --- Sessions: event pointer columns ---
+    rename_column :sessions, :mneme_boundary_event_id, :mneme_boundary_message_id
+    rename_column :sessions, :mneme_snapshot_first_event_id, :mneme_snapshot_first_message_id
+    rename_column :sessions, :mneme_snapshot_last_event_id, :mneme_snapshot_last_message_id
+    rename_column :sessions, :recalled_event_ids, :recalled_message_ids
+    rename_column :sessions, :viewport_event_ids, :viewport_message_ids
+
+    # --- Recreate FTS5 virtual table with new names ---
+    execute <<~SQL
+      CREATE VIRTUAL TABLE messages_fts USING fts5(
+        searchable_text,
+        content='',
+        contentless_delete=1,
+        tokenize='porter unicode61'
+      );
+    SQL
+
+    execute <<~SQL
+      INSERT INTO messages_fts(rowid, searchable_text)
+      SELECT m.id,
+        CASE
+          WHEN m.message_type IN ('user_message', 'agent_message', 'system_message')
+            THEN json_extract(m.payload, '$.content')
+          WHEN m.message_type = 'tool_call' AND json_extract(m.payload, '$.tool_name') = 'think'
+            THEN json_extract(m.payload, '$.tool_input.thoughts')
+        END
+      FROM messages m
+      WHERE (m.message_type IN ('user_message', 'agent_message', 'system_message'))
+         OR (m.message_type = 'tool_call' AND json_extract(m.payload, '$.tool_name') = 'think');
+    SQL
+
+    execute <<~SQL
+      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;
+    SQL
+
+    execute <<~SQL
+      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;
+    SQL
+  end
+
+  def down
+    # --- FTS5: drop new triggers and table ---
+    execute "DROP TRIGGER IF EXISTS messages_fts_insert"
+    execute "DROP TRIGGER IF EXISTS messages_fts_delete"
+    execute "DROP TABLE IF EXISTS messages_fts"
+
+    # --- Sessions: restore event pointer columns ---
+    rename_column :sessions, :mneme_boundary_message_id, :mneme_boundary_event_id
+    rename_column :sessions, :mneme_snapshot_first_message_id, :mneme_snapshot_first_event_id
+    rename_column :sessions, :mneme_snapshot_last_message_id, :mneme_snapshot_last_event_id
+    rename_column :sessions, :recalled_message_ids, :recalled_event_ids
+    rename_column :sessions, :viewport_message_ids, :viewport_event_ids
+
+    # --- Snapshots: restore event range columns ---
+    rename_column :snapshots, :from_message_id, :from_event_id
+    rename_column :snapshots, :to_message_id, :to_event_id
+
+    # --- Join table: goal_pinned_messages → goal_pinned_events ---
+    rename_column :goal_pinned_messages, :pinned_message_id, :pinned_event_id
+    rename_table :goal_pinned_messages, :goal_pinned_events
+
+    # --- Pinned messages → pinned events ---
+    rename_column :pinned_messages, :message_id, :event_id
+    rename_table :pinned_messages, :pinned_events
+
+    # --- Main table: messages → events ---
+    rename_column :messages, :message_type, :event_type
+    rename_table :messages, :events
+
+    # --- Recreate original FTS5 ---
+    execute <<~SQL
+      CREATE VIRTUAL TABLE events_fts USING fts5(
+        searchable_text,
+        content='',
+        contentless_delete=1,
+        tokenize='porter unicode61'
+      );
+    SQL
+
+    execute <<~SQL
+      INSERT INTO events_fts(rowid, searchable_text)
+      SELECT e.id,
+        CASE
+          WHEN e.event_type IN ('user_message', 'agent_message', 'system_message')
+            THEN json_extract(e.payload, '$.content')
+          WHEN e.event_type = 'tool_call' AND json_extract(e.payload, '$.tool_name') = 'think'
+            THEN json_extract(e.payload, '$.tool_input.thoughts')
+        END
+      FROM events e
+      WHERE (e.event_type IN ('user_message', 'agent_message', 'system_message'))
+         OR (e.event_type = 'tool_call' AND json_extract(e.payload, '$.tool_name') = 'think');
+    SQL
+
+    execute <<~SQL
+      CREATE TRIGGER events_fts_insert AFTER INSERT ON events
+      WHEN NEW.event_type IN ('user_message', 'agent_message', 'system_message')
+        OR (NEW.event_type = 'tool_call' AND json_extract(NEW.payload, '$.tool_name') = 'think')
+      BEGIN
+        INSERT INTO events_fts(rowid, searchable_text)
+        VALUES (
+          NEW.id,
+          CASE
+            WHEN NEW.event_type IN ('user_message', 'agent_message', 'system_message')
+              THEN json_extract(NEW.payload, '$.content')
+            WHEN NEW.event_type = 'tool_call'
+              THEN json_extract(NEW.payload, '$.tool_input.thoughts')
+          END
+        );
+      END;
+    SQL
+
+    execute <<~SQL
+      CREATE TRIGGER events_fts_delete AFTER DELETE ON events
+      WHEN OLD.event_type IN ('user_message', 'agent_message', 'system_message')
+        OR (OLD.event_type = 'tool_call' AND json_extract(OLD.payload, '$.tool_name') = 'think')
+      BEGIN
+        DELETE FROM events_fts WHERE rowid = OLD.id;
+      END;
+    SQL
+  end
+end

data/lib/agent_loop.rb

@@ -42,7 +42,7 @@ class AgentLoop
 
   # Runs the agent loop for a single user input.
   #
-  # Persists the user event directly (the global Persister skips
+  # 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.
@@ -53,7 +53,7 @@ class AgentLoop
     text = input.to_s.strip
     return if text.empty?
 
-    persist_user_event(text)
+    persist_user_message(text)
     Events::Bus.emit(Events::UserMessage.new(content: text, session_id: @session.id))
     run
   rescue => error
@@ -129,15 +129,20 @@ class AgentLoop
   # @return [Array<Class<Tools::Base>>]
   STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::Remember].freeze
 
+  # Tools that bypass {Session#granted_tools} filtering.
+  # The agent's reasoning depends on these regardless of task scope.
+  # @return [Array<Class<Tools::Base>>]
+  ALWAYS_GRANTED_TOOLS = [Tools::Think].freeze
+
   # Name-to-class mapping for tool restriction validation and registry building.
   # @return [Hash{String => Class<Tools::Base>}]
   STANDARD_TOOLS_BY_NAME = STANDARD_TOOLS.index_by(&:tool_name).freeze
 
   private
 
-  # @see Session#create_user_event
-  def persist_user_event(content)
-    @session.create_user_event(content)
+  # @see Session#create_user_message
+  def persist_user_message(content)
+    @session.create_user_message(content)
   end
 
   # Assembles LLM options (system prompt, environment context).
@@ -170,7 +175,7 @@ class AgentLoop
     unless @session.sub_agent?
       registry.register(Tools::SpawnSubagent)
       registry.register(Tools::SpawnSpecialist)
-      registry.register(Tools::RequestFeature)
+      registry.register(Tools::OpenIssue)
     end
 
     register_mcp_tools(registry)
@@ -194,12 +199,15 @@ class AgentLoop
 
   # Standard tools available to this session.
   # Returns all when {Session#granted_tools} is nil (no restriction).
-  # Returns only matching tools when granted_tools is an array.
+  # Returns only matching tools when granted_tools is an array,
+  # always including {ALWAYS_GRANTED_TOOLS}.
   #
   # @return [Array<Class<Tools::Base>>] tool classes to register
   def granted_standard_tools
-    return STANDARD_TOOLS unless @session.granted_tools
+    granted = @session.granted_tools
+    return STANDARD_TOOLS unless granted
 
-    @session.granted_tools.filter_map { |name| STANDARD_TOOLS_BY_NAME[name] }
+    explicitly_granted = granted.filter_map { |name| STANDARD_TOOLS_BY_NAME[name] }
+    (ALWAYS_GRANTED_TOOLS + explicitly_granted).uniq
   end
 end

data/lib/agents/registry.rb

@@ -37,7 +37,7 @@ module Agents
     # @return [self]
     def load_all
       load_directory(BUILTIN_DIR)
-      load_directory(USER_DIR)
+      load_directory(USER_DIR) unless Rails.env.test?
       self
     end
 

data/lib/analytical_brain/runner.rb

@@ -27,7 +27,7 @@ module AnalyticalBrain
           ──────────────────────────────
           SESSION NAMING
           ──────────────────────────────
-          Call rename_session when the topic becomes clear or shifts.
+          Name the session when the topic becomes clear. Rename if it shifts.
           Format: one emoji + 1-3 descriptive words.
         PROMPT
         tools: [Tools::RenameSession]
@@ -38,10 +38,10 @@ module AnalyticalBrain
           ──────────────────────────────
           SUB-AGENT NAMING
           ──────────────────────────────
-          Call assign_nickname to give this sub-agent a short, memorable nickname.
+          Give this sub-agent a memorable nickname based on its task.
           Format: 1-3 lowercase words joined by hyphens (e.g. "loop-sleuth", "api-scout").
-          Evocative of the task, fun, easy to type after @.
-          Generate EXACTLY ONE nickname. If taken, pick another — no numeric suffixes.
+          Evocative, fun, easy to type after @.
+          One nickname per call. If taken, pick another — no numeric suffixes.
         PROMPT
         tools: [Tools::AssignNickname]
       ),
@@ -51,8 +51,8 @@ module AnalyticalBrain
           ──────────────────────────────
           SKILL MANAGEMENT
           ──────────────────────────────
-          Call activate_skill when the conversation matches a skill's description.
-          Call deactivate_skill when the agent moves to a different domain.
+          Activate skills when the conversation enters their domain.
+          Deactivate when the agent moves to a different domain.
           Multiple skills can be active at once.
         PROMPT
         tools: [Tools::ActivateSkill, Tools::DeactivateSkill]
@@ -63,11 +63,11 @@ module AnalyticalBrain
           ──────────────────────────────
           WORKFLOW MANAGEMENT
           ──────────────────────────────
-          Call read_workflow when the user starts a multi-step task matching a workflow description.
-          Read the returned content and use judgment to create appropriate goals — not a mechanical 1:1 mapping.
+          Activate a workflow when the user starts a multi-step task that matches one.
+          Read the returned content and use judgment to create goals — not a mechanical 1:1 mapping.
           Adapt to context: skip irrelevant steps, add extra steps for unfamiliar areas.
-          Call deactivate_workflow when the workflow completes or the user shifts focus.
-          Only one workflow can be active at a time — activating a new one replaces the previous.
+          Deactivate the workflow when it completes or the user shifts focus.
+          Only one workflow active at a time — activating a new one replaces the previous.
         PROMPT
         tools: [Tools::ReadWorkflow, Tools::DeactivateWorkflow]
       ),
@@ -77,11 +77,11 @@ module AnalyticalBrain
           ──────────────────────────────
           GOAL TRACKING
           ──────────────────────────────
-          Call set_goal to create a root goal when the user starts a multi-step task.
-          Call set_goal with parent_goal_id to add sub-goals (TODO items) under it.
-          Call update_goal to refine a goal's description as understanding evolves.
-          Call finish_goal when the main agent completes work a goal describes.
-          Finishing a root goal cascades — all active sub-goals are completed too.
+          Create a root goal when the user starts a multi-step task.
+          Break it into sub-goals as the plan becomes clear.
+          Refine goal wording as understanding evolves.
+          Mark goals complete when the agent finishes the work they describe.
+          Completing a root goal cascades — all sub-goals are finished too.
           Never duplicate an existing goal — check the active goals list first.
         PROMPT
         tools: [Tools::SetGoal, Tools::UpdateGoal, Tools::FinishGoal]
@@ -89,17 +89,17 @@ module AnalyticalBrain
     }.freeze
 
     BASE_PROMPT = <<~PROMPT
-      You are a background automation that manages session metadata.
-      You MUST ONLY communicate through tool calls — NEVER output text.
-      Always finish by calling everything_is_ready.
+      You manage context for the main agent — skills, goals, workflows, and session names.
+      Watch the conversation and act when context needs updating.
+      Communicate only through tool calls — never output text.
     PROMPT
 
     COMPLETION_PROMPT = <<~PROMPT
       ──────────────────────────────
       COMPLETION
       ──────────────────────────────
-      Call everything_is_ready as your LAST tool call, every time.
-      If nothing needs changing, call it immediately as your only tool call.
+      Always finish with everything_is_ready.
+      If nothing needs attention, call it immediately.
     PROMPT
 
     # Which responsibilities activate for each session type.
@@ -118,7 +118,7 @@ module AnalyticalBrain
     end
 
     # Runs the analytical brain loop. Builds context from the session's
-    # recent events, calls the LLM with the session-appropriate tool set,
+    # recent messages, calls the LLM with the session-appropriate tool set,
     # and executes any tool calls against the session.
     #
     # Events emitted during tool execution are not persisted — the phantom
@@ -130,12 +130,12 @@ module AnalyticalBrain
       messages = build_messages
       sid = @session.id
       if messages.empty?
-        log.debug("session=#{sid} — no events, skipping")
+        log.debug("session=#{sid} — no messages, skipping")
         return
       end
 
       system = build_system_prompt
-      log.info("session=#{sid} — running (#{recent_events.size} events)")
+      log.info("session=#{sid} — running (#{recent_messages.size} messages)")
       log.debug("system prompt:\n#{system}")
       log.debug("user message:\n#{messages.first[:content]}")
 
@@ -162,18 +162,18 @@ module AnalyticalBrain
       active_responsibility_keys.map { |key| RESPONSIBILITIES.fetch(key) }
     end
 
-    # Builds a condensed transcript of recent events as a single user message.
+    # Builds a condensed transcript of recent messages as a single user message.
     # The framing differs by session type:
     #
     # * **Parent:** "The main session is working on this: [transcript]"
     # * **Child:** "A sub-agent has been spawned with this task: [transcript]"
     #
-    # @return [Array<Hash>] single-element messages array, or empty if no events
+    # @return [Array<Hash>] single-element messages array, or empty if no messages
     def build_messages
-      events = recent_events
-      return [] if events.empty?
+      messages = recent_messages
+      return [] if messages.empty?
 
-      transcript = events.filter_map { |event| EventDecorator.for(event)&.render("brain") }.join("\n")
+      transcript = messages.filter_map { |msg| MessageDecorator.for(msg)&.render("brain") }.join("\n")
 
       if @session.sub_agent?
         build_child_message(transcript)
@@ -189,7 +189,7 @@ module AnalyticalBrain
         #{transcript}
         ```
 
-        Observe the conversation and take action: manage goals, activate or deactivate relevant skills, read workflows when a multi-step task matches, rename the session if needed, then call everything_is_ready.
+        Review and take any needed actions, then call everything_is_ready.
       MSG
       [{role: "user", content: content}]
     end
@@ -201,17 +201,17 @@ module AnalyticalBrain
         #{transcript}
         ```
 
-        Assign a memorable nickname based on the task, activate relevant skills, then call everything_is_ready.
+        Assign a nickname, activate relevant skills, then call everything_is_ready.
       MSG
       [{role: "user", content: content}]
     end
 
-    # @return [Array<Event>] most recent events in chronological order
-    def recent_events
-      @session.events
-        .context_events
+    # @return [Array<Message>] most recent messages in chronological order
+    def recent_messages
+      @session.messages
+        .context_messages
         .reorder(id: :desc)
-        .limit(Anima::Settings.analytical_brain_event_window)
+        .limit(Anima::Settings.analytical_brain_message_window)
         .to_a
         .reverse
     end

data/lib/analytical_brain/tools/activate_skill.rb

@@ -8,19 +8,15 @@ module AnalyticalBrain
     class ActivateSkill < ::Tools::Base
       def self.tool_name = "activate_skill"
 
-      def self.description = "Activate a domain knowledge skill on the main session. " \
-        "The skill's content will be injected into the agent's system prompt."
+      def self.description = "Give the agent domain knowledge relevant to the current conversation."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            name: {
-              type: "string",
-              description: "Name of the skill to activate (from the available skills list)"
-            }
+            skill_name: {type: "string"}
           },
-          required: %w[name]
+          required: %w[skill_name]
         }
       end
 
@@ -29,11 +25,11 @@ module AnalyticalBrain
         @main_session = main_session
       end
 
-      # @param input [Hash<String, Object>] with "name" key
+      # @param input [Hash<String, Object>] with "skill_name" key
       # @return [String] confirmation message with skill description
       # @return [Hash] with :error key on validation failure
       def execute(input)
-        skill_name = input["name"].to_s.strip
+        skill_name = input["skill_name"].to_s.strip
         return {error: "Skill name cannot be blank"} if skill_name.empty?
 
         skill = @main_session.activate_skill(skill_name)

data/lib/analytical_brain/tools/assign_nickname.rb

@@ -17,8 +17,7 @@ module AnalyticalBrain
 
       def self.tool_name = "assign_nickname"
 
-      def self.description = "Assign a short, memorable nickname to this sub-agent. " \
-        "The nickname is permanent — it will not change."
+      def self.description = "Assign a permanent nickname to this sub-agent."
 
       def self.input_schema
         {
@@ -26,8 +25,7 @@ module AnalyticalBrain
           properties: {
             nickname: {
               type: "string",
-              description: "1-3 lowercase words joined by hyphens (e.g. 'loop-sleuth', 'api-scout'). " \
-                "Evocative of the task, fun, easy to type after @."
+              description: "Lowercase, hyphenated (e.g. 'loop-sleuth')."
             }
           },
           required: %w[nickname]

data/lib/analytical_brain/tools/deactivate_skill.rb

@@ -7,19 +7,15 @@ module AnalyticalBrain
     class DeactivateSkill < ::Tools::Base
       def self.tool_name = "deactivate_skill"
 
-      def self.description = "Deactivate a skill that is no longer relevant. " \
-        "The skill's content will be removed from the agent's system prompt."
+      def self.description = "Remove domain knowledge that is no longer relevant."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            name: {
-              type: "string",
-              description: "Name of the skill to deactivate (from the currently active skills list)"
-            }
+            skill_name: {type: "string"}
           },
-          required: %w[name]
+          required: %w[skill_name]
         }
       end
 
@@ -28,11 +24,11 @@ module AnalyticalBrain
         @main_session = main_session
       end
 
-      # @param input [Hash<String, Object>] with "name" key
+      # @param input [Hash<String, Object>] with "skill_name" key
       # @return [String] confirmation message
       # @return [Hash] with :error key on validation failure
       def execute(input)
-        skill_name = input["name"].to_s.strip
+        skill_name = input["skill_name"].to_s.strip
         return {error: "Skill name cannot be blank"} if skill_name.empty?
 
         @main_session.deactivate_skill(skill_name)

data/lib/analytical_brain/tools/everything_is_ready.rb

@@ -11,8 +11,7 @@ module AnalyticalBrain
     class EverythingIsReady < ::Tools::Base
       def self.tool_name = "everything_is_ready"
 
-      def self.description = "Signal that no changes are needed. " \
-        "Call this when the session name and active skills are already appropriate."
+      def self.description = "Nothing else to do."
 
       def self.input_schema
         {type: "object", properties: {}, required: []}

data/lib/analytical_brain/tools/finish_goal.rb

@@ -7,17 +7,13 @@ module AnalyticalBrain
     class FinishGoal < ::Tools::Base
       def self.tool_name = "finish_goal"
 
-      def self.description = "Mark a goal as completed. " \
-        "Use this when the main agent has finished the work described by the goal."
+      def self.description = "Mark a goal as completed."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            goal_id: {
-              type: "integer",
-              description: "ID of the goal to mark as completed"
-            }
+            goal_id: {type: "integer"}
           },
           required: %w[goal_id]
         }
@@ -49,7 +45,8 @@ module AnalyticalBrain
       # brain learns to check status before retrying.
       def complete(goal)
         id = goal.id
-        return {error: "Goal already completed: #{goal.description} (id: #{id})"} if goal.completed?
+        desc = goal.description
+        return {error: "Goal already completed: #{desc} (id: #{id})"} if goal.completed?
 
         released = 0
         Goal.transaction do
@@ -58,7 +55,7 @@ module AnalyticalBrain
           released = goal.release_orphaned_pins!
         end
 
-        msg = "Goal completed: #{goal.description} (id: #{id})"
+        msg = "Goal completed: #{desc} (id: #{id})"
         msg += " (released #{released} orphaned pins)" if released > 0
         msg
       end