anima-core 1.3.0 → 1.5.0

data/lib/skills/definition.rb

@@ -10,7 +10,7 @@ module Skills
   # content injected into the main agent's system prompt when active.
   #
   # Skills are passive knowledge — they describe WHAT you know, not
-  # WHAT to do. The analytical brain activates/deactivates them based
+  # WHAT to do. Melete activates/deactivates them based
   # on conversation context.
   #
   # @example Skill file format
@@ -25,7 +25,7 @@ module Skills
     # @return [String] unique skill identifier used in activate_skill(name: "...")
     attr_reader :name
 
-    # @return [String] description shown to the analytical brain for relevance matching
+    # @return [String] description shown to Melete for relevance matching
     attr_reader :description
 
     # @return [String] knowledge content (Markdown body) injected into system prompt

data/lib/skills/registry.rb

@@ -69,7 +69,7 @@ module Skills
       @skills[name]
     end
 
-    # Skill names and descriptions for inclusion in the analytical brain's context.
+    # Skill names and descriptions for inclusion in Melete's context.
     #
     # @return [Hash{String => String}] name => description
     def catalog

data/lib/tools/base.rb

@@ -50,6 +50,22 @@ module Tools
       def truncation_threshold
         Anima::Settings.max_tool_response_chars
       end
+
+      # One-line entry rendered into the system prompt's "## Available Tools"
+      # menu. Tools that return +nil+ are omitted from the menu.
+      #
+      # @return [String, nil] short capability statement, or nil to skip
+      def prompt_snippet
+        nil
+      end
+
+      # Cross-tool behavioral guidelines merged into the system prompt's
+      # "## Tool Guidelines" section. Each entry becomes a Markdown bullet.
+      #
+      # @return [Array<String>] guideline lines, or empty array to skip
+      def prompt_guidelines
+        []
+      end
     end
 
     # Subclasses whose schema depends on runtime context (e.g. session state,
@@ -64,7 +80,6 @@ module Tools
     #   end
     #
     # @see Think#dynamic_schema Budget-based maxLength
-    # @see Bash#dynamic_schema CWD in description
 
     # Accepts and discards context keywords so that the Registry can pass
     # shared dependencies (e.g. shell_session) to any tool uniformly.

data/lib/tools/bash.rb

@@ -3,12 +3,16 @@
 module Tools
   # Executes bash commands in a persistent {ShellSession}. Commands share
   # working directory, environment variables, and shell history within a
-  # conversation. Output is truncated and timeouts are enforced by the
-  # underlying session.
+  # conversation. Output is the rendered terminal text exactly as a human
+  # would see it — including the prompt, which doubles as live cwd/branch
+  # telemetry for the agent.
   #
-  # Supports two modes:
-  # - Single command via +command+ (string) — backward compatible
-  # - Batch via +commands+ (array) with +mode+ controlling error handling
+  # Two input shapes:
+  # - +command+ (string) — one command, one result.
+  # - +commands+ (array) — runs each command in order in the same shell;
+  #   all run regardless of failures (the agent reads merged output and
+  #   decides what to do). Use shell chaining (+&&+) inside a single
+  #   command if you need fail-fast.
   #
   # @see ShellSession#run
   class Bash < Base
@@ -16,6 +20,8 @@ module Tools
 
     def self.description = "Execute shell commands. Working directory and environment persist between calls."
 
+    def self.prompt_snippet = "Run shell commands."
+
     def self.input_schema
       {
         type: "object",
@@ -26,12 +32,7 @@ module Tools
           commands: {
             type: "array",
             items: {type: "string"},
-            description: "Each command gets its own timeout and result."
-          },
-          mode: {
-            type: "string",
-            enum: ["sequential", "parallel"],
-            description: "sequential (default) stops on first failure."
+            description: "Each command gets its own timeout and result. All commands run regardless of failures — use a single command with shell chaining if you need fail-fast."
           }
         }
       }
@@ -44,21 +45,10 @@ module Tools
       @session = session
     end
 
-    # Returns tool schema with the shell's current working directory
-    # embedded in the description so the agent sees it during tool
-    # selection — eliminating redundant +cd+ prefixes.
-    #
-    # @return [Hash] Anthropic tool schema with dynamic description
-    def dynamic_schema
-      schema = self.class.schema.deep_dup
-      schema[:description] = "Execute shell commands in #{@shell_session.pwd}. Working directory and environment persist between calls."
-      schema
-    end
-
     # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API.
     #   Supports optional "timeout" key (seconds) to override the global
     #   command_timeout setting for long-running operations.
-    # @return [String] formatted output with stdout, stderr, and exit code
+    # @return [String] rendered terminal output
     # @return [Hash] with :error key on failure
     def execute(input)
       timeout = input["timeout"]
@@ -68,7 +58,7 @@ module Tools
       if has_command && has_commands
         {error: "Provide either 'command' or 'commands', not both"}
       elsif has_commands
-        execute_batch(input["commands"], mode: input.fetch("mode", "sequential"), timeout: timeout)
+        execute_batch(input["commands"], timeout: timeout)
       elsif has_command
         execute_single(input["command"], timeout: timeout)
       else
@@ -78,7 +68,7 @@ module Tools
 
     private
 
-    # Executes a single command — the original code path, preserved for backward compatibility.
+    # Executes a single command — the original code path.
     def execute_single(command, timeout: nil)
       command = command.to_s
       return {error: "Command cannot be blank"} if command.strip.empty?
@@ -88,25 +78,24 @@ module Tools
       return format_interrupted(result) if result[:interrupted]
       return result if result.key?(:error)
 
-      format_result(result[:stdout], result[:stderr], result[:exit_code])
+      result[:output]
     end
 
-    # Executes an array of commands, returning a combined result string.
-    # Checks for user interrupt between commands and during each command
-    # via the {ShellSession} interrupt_check callback.
+    # Executes an array of commands sequentially through the shared
+    # shell. Continues past errors — the LLM reads the merged output
+    # and decides what to do. The only short-circuit is a user interrupt,
+    # which skips the remaining commands.
     #
     # @param commands [Array<String>] commands to execute
-    # @param mode [String] "sequential" (stop on first failure) or "parallel" (run all)
     # @param timeout [Integer, nil] per-command timeout override
     # @return [String] combined results with per-command headers
     # @return [Hash] with :error key if commands array is invalid
-    def execute_batch(commands, mode:, timeout: nil)
+    def execute_batch(commands, timeout: nil)
       return {error: "Commands array cannot be empty"} unless commands.is_a?(Array) && commands.any?
 
       checker = interrupt_checker
       total = commands.size
       results = []
-      failed = false
       interrupted = false
 
       commands.each_with_index do |command, index|
@@ -117,11 +106,6 @@ module Tools
           next
         end
 
-        if failed && mode == "sequential"
-          results << "#{position} $ #{command}\n(skipped)"
-          next
-        end
-
         command = command.to_s
         if command.strip.empty?
           results << "#{position} $ (blank)\n(skipped — blank command)"
@@ -135,37 +119,23 @@ module Tools
           interrupted = true
         elsif result.key?(:error)
           results << "#{position} $ #{command}\n#{result[:error]}"
-          failed = true
         else
-          exit_code = result[:exit_code]
-          output = format_result(result[:stdout], result[:stderr], exit_code)
-          results << "#{position} $ #{command}\n#{output}"
-          failed = true if exit_code != 0
+          results << "#{position} $ #{command}\n#{result[:output]}"
         end
       end
 
       results.join("\n\n")
     end
 
-    def format_result(stdout, stderr, exit_code)
-      parts = []
-      parts << "stdout:\n#{stdout}" unless stdout.empty?
-      parts << "stderr:\n#{stderr}" unless stderr.empty?
-      parts << "exit_code: #{exit_code}"
-      parts.join("\n\n")
-    end
-
     # Formats the result of an interrupted command for the LLM.
     # Includes partial output captured before the interrupt.
     #
-    # @param result [Hash] ShellSession result with :stdout, :stderr keys
+    # @param result [Hash] ShellSession result with :output key
     # @return [String] formatted message for the LLM
     def format_interrupted(result)
-      stdout = result[:stdout].to_s
-      stderr = result[:stderr].to_s
+      output = result[:output].to_s
       parts = [LLM::Client::INTERRUPT_MESSAGE]
-      parts << "Partial stdout:\n#{stdout}" unless stdout.empty?
-      parts << "stderr:\n#{stderr}" unless stderr.empty?
+      parts << "Partial output:\n#{output}" unless output.empty?
       parts.join("\n\n")
     end
 

data/lib/tools/edit.rb

@@ -20,6 +20,8 @@ module Tools
 
     def self.description = "Replace text in a file."
 
+    def self.prompt_snippet = "Replace exact text in a file."
+
     def self.input_schema
       {
         type: "object",

data/lib/tools/mark_goal_completed.rb

@@ -63,9 +63,9 @@ module Tools
       end
     end
 
-    # Delivers the sub-agent's result to the parent session as an
-    # attributed user message. Truncates oversized results to protect
-    # the parent's context window. No-op when the parent session is absent.
+    # Delivers the sub-agent's result to the parent session with source
+    # metadata. Truncates oversized results to protect the parent's
+    # context window. No-op when the parent session is absent.
     #
     # @param result [String] the sub-agent's findings to forward
     # @return [void]
@@ -79,8 +79,7 @@ module Tools
         threshold: Anima::Settings.max_subagent_response_chars,
         reason: "sub-agent output displays first/last #{Tools::ResponseTruncator::HEAD_LINES} lines"
       )
-      attributed = format(Tools::ResponseTruncator::ATTRIBUTION_FORMAT, name, truncated)
-      parent.enqueue_user_message(attributed)
+      parent.enqueue_user_message(truncated, source_type: "subagent", source_name: name)
     end
   end
 end

data/lib/tools/read.rb

@@ -21,6 +21,8 @@ module Tools
 
     def self.description = "Read file. Relative paths resolve against working directory."
 
+    def self.prompt_snippet = "Read a file."
+
     def self.input_schema
       {
         type: "object",

data/lib/tools/registry.rb

@@ -14,6 +14,76 @@ module Tools
   #   registry.register(Tools::Bash)
   #   registry.execute("bash", {"command" => "ls"})
   class Registry
+    # Standard tools available to every session unless filtered out by
+    # {Session#granted_tools}.
+    STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::ViewMessages, Tools::SearchMessages].freeze
+
+    # Tools that bypass {Session#granted_tools} filtering — the agent's
+    # reasoning depends on them regardless of task scope.
+    ALWAYS_GRANTED_TOOLS = [Tools::Think].freeze
+
+    # Name-to-class mapping for granted-tools filtering.
+    STANDARD_TOOLS_BY_NAME = STANDARD_TOOLS.index_by(&:tool_name).freeze
+
+    class << self
+      # Builds a registry appropriate for the given session: standard tools
+      # filtered through {Session#granted_tools}, plus spawn tools for main
+      # sessions or +mark_goal_completed+ for sub-agents, plus any tools
+      # exposed by configured MCP servers.
+      #
+      # MCP registration warnings are emitted as system messages so both the
+      # user (in verbose mode) and the LLM see them.
+      #
+      # @param session [Session] the session requesting tools
+      # @param shell_session [ShellSession] persistent PTY for Bash-family tools
+      # @return [Registry] configured registry
+      def build(session:, shell_session:)
+        registry = new(context: {shell_session: shell_session, session: session})
+
+        tool_classes_for(session).each { |tool| registry.register(tool) }
+
+        Mcp::ClientManager.shared.register_tools(registry).each do |message|
+          Events::Bus.emit(Events::SystemMessage.new(content: message, session_id: session.id))
+        end
+
+        registry
+      end
+
+      # Resolves the ordered tool-class list for a session: granted standard
+      # tools (or all of them when +granted_tools+ is nil), plus spawn tools
+      # for main sessions or +mark_goal_completed+ for sub-agents. MCP tools
+      # are excluded — they are dynamic and registered separately by
+      # {.build}. Single source of truth for {.build}, {Session#tool_schemas},
+      # and the system-prompt section assemblers.
+      #
+      # @param session [Session]
+      # @return [Array<Class<Tools::Base>>]
+      def tool_classes_for(session)
+        tools = granted_standard_tools(session).dup
+
+        if session.sub_agent?
+          tools.push(Tools::MarkGoalCompleted)
+        else
+          tools.push(Tools::SpawnSubagent, Tools::SpawnSpecialist, Tools::OpenIssue)
+        end
+
+        tools
+      end
+
+      private
+
+      # Filters {STANDARD_TOOLS} through the session's granted list.
+      # Always includes {ALWAYS_GRANTED_TOOLS} so the agent retains core
+      # reasoning tools regardless of task scope.
+      def granted_standard_tools(session)
+        granted = session.granted_tools
+        return STANDARD_TOOLS unless granted
+
+        explicitly_granted = granted.filter_map { |name| STANDARD_TOOLS_BY_NAME[name] }
+        (ALWAYS_GRANTED_TOOLS + explicitly_granted).uniq
+      end
+    end
+
     # @return [Hash{String => Class, Object}] registered tools keyed by name
     attr_reader :tools
 
@@ -38,22 +108,33 @@ module Tools
     #   are instantiated with context to generate their schema:
     #   - {Think}: budget-based maxLength
     #   - {Bash}: CWD embedded in description
+    # Returns tool schemas for the Anthropic API. The last schema is
+    # annotated with +cache_control+ so the API caches the entire tools
+    # prefix (tools are evaluated first in cache prefix order).
     def schemas
       default = Anima::Settings.tool_timeout
-      @tools.values.map { |tool| inject_timeout(resolve_schema(tool), default) }
+      result = @tools.values.map { |tool| inject_timeout(resolve_schema(tool), default) }
+      result.last[:cache_control] = {type: "ephemeral"}
+      result
     end
 
     # Execute a tool by name. Classes are instantiated with the registry's
-    # context; instances are called directly.
+    # context; instances are called directly. The enclosing +tool_use_id+
+    # is merged into the context when provided so tools that need to
+    # reference their own invoking tool_call (e.g. {Tools::SpawnSubagent}
+    # persisting +spawn_tool_use_id+ on the child session) can read it via
+    # a named kwarg in their initializer.
     #
     # @param name [String] registered tool name
     # @param input [Hash] tool input parameters (may include "timeout" for
     #   tools that support per-call timeout overrides)
+    # @param tool_use_id [String, nil] the invoking tool_call's pairing id
     # @return [String, Hash] tool execution result
     # @raise [UnknownToolError] if no tool is registered with the given name
-    def execute(name, input)
+    def execute(name, input, tool_use_id: nil)
       tool = @tools.fetch(name) { raise UnknownToolError, "Unknown tool: #{name}" }
-      instance = tool.is_a?(Class) ? tool.new(**@context) : tool
+      context = tool_use_id ? @context.merge(tool_use_id: tool_use_id) : @context
+      instance = tool.is_a?(Class) ? tool.new(**context) : tool
       instance.execute(input)
     end
 

data/lib/tools/response_truncator.rb

@@ -24,7 +24,7 @@ module Tools
     # Attribution prefix for messages routed from sub-agent to parent.
     # Shared by {Events::Subscribers::SubagentMessageRouter} and
     # {Tools::MarkGoalCompleted} to keep formatting consistent.
-    ATTRIBUTION_FORMAT = "[sub-agent @%s]: %s"
+    ATTRIBUTION_FORMAT = "[sub-agent %s]: %s"
 
     NOTICE = <<~NOTICE.strip
       ---

data/lib/tools/{recall.rb → search_messages.rb}

@@ -1,51 +1,49 @@
 # frozen_string_literal: true
 
 module Tools
-  # Active memory search — keyword lookup across conversation history.
-  # Returns ranked snippets with message IDs for drill-down via {Remember}.
+  # Keyword search across long-term memory — every message Anima has
+  # ever seen, across every session, *except* what the agent is already
+  # looking at right now. Results sit below her current viewport; anything
+  # still in front of her is excluded, so every slot the search returns is
+  # new information.
   #
   # Two-step memory workflow:
-  #   1. `recall(query: "auth flow")` → discovers relevant messages
-  #   2. `remember(message_id: 42)` → fractal zoom into full context
+  #   1. `search_messages(query: "auth flow")` → discovers relevant messages
+  #   2. `view_messages(message_id: 42)` → fractal zoom into full context
   #
-  # Wraps {Mneme::Search} — same FTS5 engine used by passive recall,
-  # but triggered on demand by the agent instead of automatically by goals.
+  # Same FTS5 engine Mneme uses for passive recall — this variant fires
+  # on demand when Aoide reaches for a memory herself.
   #
-  # @example Search all sessions
-  #   recall(query: "authentication flow")
-  #
-  # @example Search current session only
-  #   recall(query: "OAuth config", session_only: true)
-  class Recall < Base
-    def self.tool_name = "recall"
+  # @example
+  #   search_messages(query: "authentication flow")
+  class SearchMessages < Base
+    def self.tool_name = "search_messages"
 
-    def self.description = "Find messages across past conversations by keywords."
+    def self.description = "Search long-term memory (past conversations outside your current viewport) by keyword. Returns ranked message snippets with IDs — pass any ID to view_messages to see the full context around it."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          query: {type: "string"},
-          session_only: {type: "boolean", description: "Default: all sessions"}
+          query: {type: "string"}
         },
         required: ["query"]
       }
     end
 
-    # @param session [Session] the current session (used for session_only scoping)
+    # @param session [Session] the calling session — drives viewport exclusion
     def initialize(session:, **)
       @session = session
     end
 
-    # @param input [Hash] with "query" and optional "session_only"
+    # @param input [Hash] with "query"
     # @return [String] formatted search results with message IDs
     # @return [Hash] with :error key when query is blank
     def execute(input)
       query = input["query"].to_s.strip
       return {error: "Query cannot be blank"} if query.empty?
 
-      session_id = (input["session_only"] == true) ? @session.id : nil
-      results = Mneme::Search.query(query, session_id: session_id)
+      results = Mneme::Search.query(query, caller_session: @session)
 
       return "No results found for \"#{query}\"." if results.empty?
 
@@ -55,7 +53,7 @@ module Tools
     private
 
     # Formats results as token-efficient, LLM-readable output.
-    # Each result includes message_id for drill-down via remember tool.
+    # Each result includes message_id for drill-down via view_messages.
     #
     # @param query [String] the original search query
     # @param results [Array<Mneme::Search::Result>] ranked search results

data/lib/tools/spawn_specialist.rb

@@ -5,7 +5,7 @@ module Tools
   # The specialist has a predefined system prompt and tool set defined
   # in its Markdown definition file under agents/.
   #
-  # Nickname assignment is handled by the {AnalyticalBrain::Runner} which
+  # Nickname assignment is handled by the {Melete::Runner} which
   # runs synchronously at spawn time, generating a unique nickname based
   # on the task — same as generic sub-agents.
   #
@@ -22,8 +22,8 @@ module Tools
     # Builds description dynamically to include available specialists.
     def self.description
       base = "Need a specific skill set for the job? Bring in a specialist. " \
-        "Its messages appear in yours; any message containing " \
-        "@nickname is forwarded — even casual mentions will wake it."
+        "Its messages appear as tool responses in your conversation. " \
+        "Prefix its nickname with @ to send instructions."
 
       registry = Agents::Registry.instance
       return base unless registry.any?
@@ -59,14 +59,21 @@ module Tools
 
     # @param session [Session] the parent session spawning the specialist
     # @param agent_registry [Agents::Registry, nil] injectable for testing
-    def initialize(session:, agent_registry: nil, **)
+    # @param tool_use_id [String, nil] the invoking +spawn_specialist+ tool_call's
+    #   pairing id, captured so the spawn pair can later be located by the
+    #   HUD visibility sweep in {Mneme::Runner}
+    def initialize(session:, agent_registry: nil, tool_use_id: nil, **)
       @session = session
       @agent_registry = agent_registry || Agents::Registry.instance
+      @tool_use_id = tool_use_id
     end
 
-    # Creates a child session with the specialist's predefined prompt and tools,
-    # persists the task as a user message, and queues background processing.
-    # Returns immediately (non-blocking).
+    # Creates a child session with the specialist's predefined prompt and
+    # tools, pins the task as a Goal, and enqueues the task as the
+    # child's first user_message PendingMessage — which kicks the
+    # standard inbound pipeline (Melete → (Mneme) → StartProcessing →
+    # DrainJob) so the specialist self-starts the same way a human-typed
+    # message would. Returns immediately after Melete completes.
     #
     # @param input [Hash<String, Object>] with "name" and "task"
     # @return [String] confirmation with child session ID
@@ -83,10 +90,9 @@ module Tools
 
       child = spawn_child(definition, task)
       nickname = child.name
-      "Specialist @#{nickname} spawned (session #{child.id}). " \
+      "Specialist #{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
-        "Reply with @#{nickname} to send it instructions — " \
-        "any message mentioning @#{nickname} is forwarded, even in narration."
+        "To address it, prefix its name with @ in your message."
     end
 
     private
@@ -95,12 +101,14 @@ module Tools
       child = Session.create!(
         parent_session_id: @session.id,
         prompt: build_prompt(definition),
-        granted_tools: definition.tools
+        granted_tools: definition.tools,
+        spawn_tool_use_id: @tool_use_id,
+        initial_cwd: ShellSession.cwd_via_tmux(@session.id) || @session.initial_cwd
       )
-      pin_goal_and_frame(child, task)
-      assign_nickname_via_brain(child)
+      create_goal_with_pinned_task(child, task)
+      assign_nickname_via_melete(child)
       child.broadcast_children_update_to_parent
-      AgentRequestJob.perform_later(child.id)
+      child.enqueue_user_message(task)
       child
     end
 

data/lib/tools/spawn_subagent.rb

@@ -2,12 +2,13 @@
 
 module Tools
   # Spawns a generic child session that works on a task autonomously.
-  # The sub-agent inherits the parent's viewport context at fork time,
-  # runs via {AgentRequestJob}, and communicates with the parent through
+  # The sub-agent starts clean — no parent conversation history — with
+  # only a system prompt, a Goal, and the task as its first user message.
+  # Runs via {DrainJob} and communicates with the parent through
   # natural text messages routed by {Events::Subscribers::SubagentMessageRouter}.
   #
-  # Nickname assignment is handled by the {AnalyticalBrain::Runner} which
-  # runs synchronously at spawn time — the same brain that manages skills,
+  # Nickname assignment is handled by the {Melete::Runner} which
+  # runs synchronously at spawn time — the same muse that manages skills,
   # goals, and workflows for the main session.
   #
   # For named specialists with predefined prompts and tools, see {SpawnSpecialist}.
@@ -20,9 +21,9 @@ module Tools
 
     def self.description
       "Task feels like a sidequest or a context-switch? Hand it off. " \
-        "Inherits your context; its messages appear in yours. " \
-        "Any message containing @nickname is forwarded — " \
-        "even casual mentions will wake the sub-agent."
+        "Starts clean with just the task — include all relevant context in the task description. " \
+        "Its messages appear as tool responses in your conversation. " \
+        "Prefix its nickname with @ to send instructions."
     end
 
     def self.input_schema
@@ -35,7 +36,7 @@ module Tools
             items: {type: "string"},
             description: "Tool names to grant the sub-agent. " \
               "Omit for all standard tools. Empty array for pure reasoning. " \
-              "Valid tools: #{AgentLoop::STANDARD_TOOLS_BY_NAME.keys.join(", ")}"
+              "Valid tools: #{Tools::Registry::STANDARD_TOOLS_BY_NAME.keys.join(", ")}"
           }
         },
         required: %w[task]
@@ -43,13 +44,21 @@ module Tools
     end
 
     # @param session [Session] the parent session spawning the sub-agent
-    def initialize(session:, **)
+    # @param tool_use_id [String, nil] the invoking +spawn_subagent+ tool_call's
+    #   pairing id, captured so the spawn pair can later be located by the
+    #   HUD visibility sweep in {Mneme::Runner}
+    def initialize(session:, tool_use_id: nil, **)
       @session = session
+      @tool_use_id = tool_use_id
     end
 
-    # Creates a child session, runs the analytical brain to assign a nickname,
-    # persists the task as a user message, and queues background processing.
-    # Returns immediately after brain completes (blocking for ~200ms).
+    # Creates a child session with a clean context (no parent history),
+    # runs Melete to assign a nickname, pins the task as a Goal, and
+    # enqueues the task as the child's first user_message PendingMessage —
+    # which kicks the standard inbound pipeline (Melete → (Mneme) →
+    # StartProcessing → DrainJob) so the sub-agent self-starts the same
+    # way a human-typed message would. Returns immediately after Melete
+    # completes (blocking for ~200ms).
     #
     # @param input [Hash<String, Object>] with "task" and optional "tools"
     # @return [String] confirmation with child session ID and @nickname
@@ -66,10 +75,9 @@ module Tools
 
       child = spawn_child(task, tools)
       nickname = child.name
-      "Sub-agent @#{nickname} spawned (session #{child.id}). " \
+      "Sub-agent #{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
-        "Reply with @#{nickname} to send it instructions — " \
-        "any message mentioning @#{nickname} is forwarded, even in narration."
+        "To address it, prefix its name with @ in your message."
     end
 
     private
@@ -78,12 +86,14 @@ module Tools
       child = Session.create!(
         parent_session_id: @session.id,
         prompt: GENERIC_PROMPT,
-        granted_tools: granted_tools
+        granted_tools: granted_tools,
+        spawn_tool_use_id: @tool_use_id,
+        initial_cwd: ShellSession.cwd_via_tmux(@session.id) || @session.initial_cwd
       )
-      pin_goal_and_frame(child, task)
-      assign_nickname_via_brain(child)
+      create_goal_with_pinned_task(child, task)
+      assign_nickname_via_melete(child)
       child.broadcast_children_update_to_parent
-      AgentRequestJob.perform_later(child.id)
+      child.enqueue_user_message(task)
       child
     end
 
@@ -105,7 +115,7 @@ module Tools
       return nil unless tools
       return {error: "tools must be an array"} unless tools.is_a?(Array)
 
-      unknown = tools - AgentLoop::STANDARD_TOOLS_BY_NAME.keys
+      unknown = tools - Tools::Registry::STANDARD_TOOLS_BY_NAME.keys
       return {error: "Unknown tool: #{unknown.first}"} if unknown.any?
 
       nil