anima-core 1.1.3 → 1.3.0

data/lib/shell_session.rb

@@ -47,13 +47,17 @@ class ShellSession
   # @param command [String] bash command to execute
   # @param timeout [Integer, nil] per-call timeout in seconds; overrides
   #   Settings.command_timeout when provided
+  # @param interrupt_check [Proc, nil] callable returning truthy when the
+  #   user has requested an interrupt. Polled every
+  #   {Anima::Settings.interrupt_check_interval} seconds during command execution.
   # @return [Hash] with :stdout, :stderr, :exit_code keys on success
+  # @return [Hash] with :interrupted, :stdout, :stderr keys on user interrupt
   # @return [Hash] with :error key on failure
-  def run(command, timeout: nil)
+  def run(command, timeout: nil, interrupt_check: nil)
     @mutex.synchronize do
       return {error: "Shell session is not running"} if @finalized
       restart unless @alive
-      execute_in_pty(command, timeout: timeout)
+      execute_in_pty(command, timeout: timeout, interrupt_check: interrupt_check)
     end
   rescue => error # rubocop:disable Lint/RescueException -- LLM must always get a result hash, never a stack trace
     {error: "#{error.class}: #{error.message}"}
@@ -229,7 +233,7 @@ class ShellSession
     end
   end
 
-  def execute_in_pty(command, timeout: nil)
+  def execute_in_pty(command, timeout: nil, interrupt_check: nil)
     clear_stderr
     marker = "__ANIMA_#{SecureRandom.hex(8)}__"
     timeout ||= Anima::Settings.command_timeout
@@ -237,10 +241,21 @@ class ShellSession
 
     @pty_stdin.puts "#{command}; __anima_ec=$?; echo; echo '#{marker}' $__anima_ec"
 
-    stdout, exit_code = read_until_marker(marker, deadline: deadline)
+    stdout, exit_code = read_until_marker(marker, deadline: deadline, interrupt_check: interrupt_check)
+
+    if exit_code == :interrupted
+      recover_shell
+      update_pwd
+      stderr = drain_stderr
+      return {
+        interrupted: true,
+        stdout: truncate(stdout),
+        stderr: truncate(stderr)
+      }
+    end
 
     if exit_code.nil?
-      recover_from_timeout
+      recover_shell
       stderr = drain_stderr
       parts = ["Command timed out after #{timeout} seconds."]
       parts << "Partial stdout:\n#{truncate(stdout)}" unless stdout.empty?
@@ -267,14 +282,23 @@ class ShellSession
   #
   # @param marker [String] unique marker to detect command completion
   # @param deadline [Float] monotonic clock deadline
+  # @param interrupt_check [Proc, nil] callable returning truthy on user interrupt
   # @return [Array(String, Integer)] stdout and exit code on success
+  # @return [Array(String, Symbol)] partial stdout and +:interrupted+ on user interrupt
   # @return [Array(String, nil)] partial stdout and nil exit code on timeout
-  def read_until_marker(marker, deadline:)
+  def read_until_marker(marker, deadline:, interrupt_check: nil)
     lines = []
     exit_code = nil
+    check_interval = interrupt_check ? [Anima::Settings.interrupt_check_interval, 0.5].max : nil
 
     loop do
-      line = gets_with_deadline(deadline)
+      line = gets_with_deadline(deadline, interrupt_check: interrupt_check, check_interval: check_interval)
+
+      if line == :interrupted
+        exit_code = :interrupted
+        break
+      end
+
       break if line.nil?
 
       line = line.chomp.delete("\r")
@@ -315,12 +339,21 @@ class ShellSession
   # Timeout.timeout (which uses Thread.raise that can corrupt mutex state
   # and leave resources inconsistent).
   #
+  # When +interrupt_check+ is provided, IO.select uses a shorter timeout
+  # (capped at {Anima::Settings.interrupt_check_interval}) and polls the
+  # callback between iterations. Returns +:interrupted+ when the callback
+  # fires, allowing the caller to send Ctrl+C and return partial output.
+  #
   # @param deadline [Float] monotonic clock deadline
+  # @param interrupt_check [Proc, nil] callable returning truthy on user interrupt
+  # @param check_interval [Float, nil] resolved interrupt check interval (seconds);
+  #   pre-computed by the caller to avoid re-reading Settings on every line
   # @return [String] line including trailing newline
+  # @return [:interrupted] when user interrupt detected
   # @return [nil] if deadline expired
   # @raise [Errno::EIO] when the PTY child process exits (Linux)
   # @raise [IOError] when the PTY file descriptor is closed
-  def gets_with_deadline(deadline)
+  def gets_with_deadline(deadline, interrupt_check: nil, check_interval: nil)
     loop do
       if (idx = @read_buffer.index("\n"))
         return @read_buffer.slice!(0..idx)
@@ -329,24 +362,29 @@ class ShellSession
       remaining = deadline - monotonic_now
       return nil if remaining <= 0
 
-      ready = IO.select([@pty_stdout], nil, nil, remaining)
-      return nil unless ready
+      select_timeout = check_interval ? [remaining, check_interval].min : remaining
 
-      begin
-        @read_buffer << @pty_stdout.read_nonblock(4096)
-      rescue IO::WaitReadable
-        # Spurious wakeup from IO.select — retry
+      ready = IO.select([@pty_stdout], nil, nil, select_timeout)
+
+      if ready
+        begin
+          @read_buffer << @pty_stdout.read_nonblock(4096)
+        rescue IO::WaitReadable
+          # Spurious wakeup from IO.select — retry
+        end
       end
+
+      return :interrupted if interrupt_check&.call
     end
   end
 
-  # Sends Ctrl+C to interrupt the running command and drains leftover output.
+  # Sends Ctrl+C and drains leftover output after a timeout or user interrupt.
   # If recovery fails, marks the session as dead (will be respawned on next run).
   #
   # @return [void]
   # @raise [Errno::EIO] when the PTY child process has exited
   # @raise [IOError] when the PTY file descriptor is closed
-  def recover_from_timeout
+  def recover_shell
     @pty_stdin.write("\x03")
     sleep 0.1
     marker = "__ANIMA_RECOVER_#{SecureRandom.hex(8)}__"

data/lib/tools/base.rb

@@ -41,8 +41,31 @@ module Tools
       def schema
         {name: tool_name, description: description, input_schema: input_schema}
       end
+
+      # Per-tool character threshold for response truncation.
+      # Override in subclasses to use a custom limit, or return +nil+
+      # to skip truncation entirely (e.g. read_file tool has its own pagination).
+      #
+      # @return [Integer, nil] character threshold, or nil to skip truncation
+      def truncation_threshold
+        Anima::Settings.max_tool_response_chars
+      end
     end
 
+    # Subclasses whose schema depends on runtime context (e.g. session state,
+    # shell working directory) can implement +#dynamic_schema+. The registry
+    # calls it instead of the class-level {.schema} when present.
+    #
+    # @example
+    #   def dynamic_schema
+    #     schema = self.class.schema.deep_dup
+    #     schema[:description] = "Dynamic: #{@some_state}"
+    #     schema
+    #   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.
     # Subclasses that need specific context should override with named kwargs.

data/lib/tools/bash.rb

@@ -14,40 +14,45 @@ module Tools
   class Bash < Base
     def self.tool_name = "bash"
 
-    def self.description
-      <<~DESC.squish
-        Execute a bash command. Working directory and environment persist across calls within a conversation.
-        Accepts either `command` (string) for a single command, or `commands` (array of strings) to run
-        multiple commands as a batch — each command gets its own timeout and result. Batch `mode` controls
-        error handling: "sequential" (default) stops on the first failure, "parallel" runs all regardless.
-      DESC
-    end
+    def self.description = "Execute shell commands. Working directory and environment persist between calls."
 
     def self.input_schema
       {
         type: "object",
         properties: {
           command: {
-            type: "string",
-            description: "The bash command to execute"
+            type: "string"
           },
           commands: {
             type: "array",
             items: {type: "string"},
-            description: "Array of bash commands to execute as a batch. Each runs independently with its own timeout and result."
+            description: "Each command gets its own timeout and result."
           },
           mode: {
             type: "string",
             enum: ["sequential", "parallel"],
-            description: 'Batch error handling: "sequential" (default) stops on first non-zero exit; "parallel" runs all commands regardless of failures.'
+            description: "sequential (default) stops on first failure."
           }
         }
       }
     end
 
     # @param shell_session [ShellSession] persistent shell backing this tool
-    def initialize(shell_session:, **)
+    # @param session [Session] conversation session for interrupt checking
+    def initialize(shell_session:, session:, **)
       @shell_session = shell_session
+      @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.
@@ -78,13 +83,18 @@ module Tools
       command = command.to_s
       return {error: "Command cannot be blank"} if command.strip.empty?
 
-      result = @shell_session.run(command, timeout: timeout)
+      result = @shell_session.run(command, timeout: timeout, interrupt_check: interrupt_checker)
+
+      return format_interrupted(result) if result[:interrupted]
       return result if result.key?(:error)
 
       format_result(result[:stdout], result[:stderr], result[:exit_code])
     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.
+    #
     # @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
@@ -93,13 +103,20 @@ module Tools
     def execute_batch(commands, mode:, 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|
         position = "[#{index + 1}/#{total}]"
 
+        if interrupted
+          results << "#{position} $ #{command}\n(skipped — interrupted by user)"
+          next
+        end
+
         if failed && mode == "sequential"
           results << "#{position} $ #{command}\n(skipped)"
           next
@@ -111,9 +128,12 @@ module Tools
           next
         end
 
-        result = @shell_session.run(command, timeout: timeout)
+        result = @shell_session.run(command, timeout: timeout, interrupt_check: checker)
 
-        if result.key?(:error)
+        if result[:interrupted]
+          results << "#{position} $ #{command}\n#{format_interrupted(result)}"
+          interrupted = true
+        elsif result.key?(:error)
           results << "#{position} $ #{command}\n#{result[:error]}"
           failed = true
         else
@@ -134,5 +154,29 @@ module Tools
       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
+    # @return [String] formatted message for the LLM
+    def format_interrupted(result)
+      stdout = result[:stdout].to_s
+      stderr = result[:stderr].to_s
+      parts = [LLM::Client::INTERRUPT_MESSAGE]
+      parts << "Partial stdout:\n#{stdout}" unless stdout.empty?
+      parts << "stderr:\n#{stderr}" unless stderr.empty?
+      parts.join("\n\n")
+    end
+
+    # Builds a lambda that checks the database for a pending interrupt flag.
+    # Called every {Anima::Settings.interrupt_check_interval} seconds during
+    # command execution inside {ShellSession}.
+    #
+    # @return [Proc] lambda returning truthy when interrupt is pending
+    def interrupt_checker
+      session_id = @session.id
+      -> { Session.where(id: session_id, interrupt_requested: true).exists? }
+    end
   end
 end

data/lib/tools/edit.rb

@@ -16,19 +16,17 @@ module Tools
   #                "new_text" => "def greet\n  'hello'\nend")
   #   # => "--- app.rb\n+++ app.rb\n@@ -1,3 +1,3 @@\n ..."
   class Edit < Base
-    def self.tool_name = "edit"
+    def self.tool_name = "edit_file"
 
-    def self.description = "Replace exact text in a file. old_text must match exactly one location; " \
-                           "include surrounding lines for uniqueness. Use for surgical edits; " \
-                           "use write for new files or full replacement."
+    def self.description = "Replace text in a file."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
-          old_text: {type: "string", description: "Exact text to find (must match exactly one location — include surrounding context if needed)"},
-          new_text: {type: "string", description: "Replacement text (empty string to delete)"}
+          path: {type: "string", description: "Relative paths resolve against working directory."},
+          old_text: {type: "string", description: "Must match exactly one location. Include surrounding lines for uniqueness."},
+          new_text: {type: "string", description: "Empty string to delete."}
         },
         required: %w[path old_text new_text]
       }
@@ -134,7 +132,7 @@ module Tools
 
       {error: "Could not find old_text in #{path}. " \
               "Verify the text exists and matches exactly (including whitespace). " \
-              "Use the read tool to check current file contents."}
+              "Use the read_file tool to check current file contents."}
     end
 
     def ambiguity_error(positions, content, path, fuzzy: false)

data/lib/tools/mark_goal_completed.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Tools
+  # Signals sub-agent task completion by marking its assigned Goal as
+  # completed and routing the result back to the parent session.
+  #
+  # Only available to sub-agent sessions (those with a +parent_session+).
+  # This is the explicit "finish line" that prevents runaway sub-agents
+  # from continuing past their assigned task.
+  #
+  # The result text is delivered to the parent session as a user message
+  # attributed to the sub-agent, identical to how regular sub-agent
+  # messages are routed by {Events::Subscribers::SubagentMessageRouter}.
+  #
+  # @example Sub-agent completing its task
+  #   mark_goal_completed(result: "Found 3 N+1 queries in the orders controller.")
+  class MarkGoalCompleted < Base
+    def self.tool_name = "mark_goal_completed"
+
+    def self.description = "Deliver result to parent. Stop working after this call."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          result: {type: "string"}
+        },
+        required: %w[result]
+      }
+    end
+
+    # @param session [Session] the sub-agent session
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # Completes the sub-agent's assigned goal and routes the result
+    # to the parent session.
+    #
+    # @param input [Hash<String, Object>] with "result"
+    # @return [String] confirmation message
+    # @return [Hash{Symbol => String}] with :error key on failure
+    def execute(input)
+      result = input["result"].to_s.strip
+      return {error: "Result cannot be blank"} if result.empty?
+
+      goal = @session.goals.active.root.first
+      return {error: "No active goal found"} unless goal
+
+      complete_goal(goal)
+      route_result_to_parent(result)
+
+      "Done. Result delivered to parent."
+    end
+
+    private
+
+    def complete_goal(goal)
+      Goal.transaction do
+        goal.update!(status: "completed", completed_at: Time.current)
+        goal.cascade_completion!
+        goal.release_orphaned_pins!
+      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.
+    #
+    # @param result [String] the sub-agent's findings to forward
+    # @return [void]
+    def route_result_to_parent(result)
+      parent = @session.parent_session
+      return unless parent
+
+      name = @session.name || "agent-#{@session.id}"
+      truncated = Tools::ResponseTruncator.truncate(
+        result,
+        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)
+    end
+  end
+end

data/lib/tools/{request_feature.rb → open_issue.rb}

@@ -3,32 +3,29 @@
 require "open3"
 
 module Tools
-  # Creates a GitHub issue via the +gh+ CLI, letting the agent request
-  # capabilities it discovers are missing during real work. Every issue
-  # is tagged with the label from +[github] label+ in +config.toml+ so
-  # the developer can filter agent-originated requests from human ones.
+  # Opens a GitHub issue on Anima's repository via the +gh+ CLI,
+  # giving the agent a voice to report bugs, pain points, or ideas.
+  # Every issue is tagged with the label from +[github] label+ in
+  # +config.toml+ so maintainers can filter agent-originated issues.
   #
   # The repository is read from +[github] repo+ in +config.toml+; when
   # unset, the tool falls back to parsing the +origin+ remote URL.
   #
   # @see https://github.com/hoblin/anima/issues/103
-  class RequestFeature < Base
+  class OpenIssue < Base
     # @return [String] tool identifier used in the Anthropic API schema
-    def self.tool_name = "request_feature"
+    def self.tool_name = "open_issue"
 
-    # @return [String] motivational description shown to the LLM
-    def self.description
-      "Don't have the right tool for this task? Request it! " \
-        "Creates a GitHub issue so the developer knows what you need."
-    end
+    # @return [String] description shown to the LLM
+    def self.description = "Something broken, missing, or could be better in Anima? Say it here."
 
     # @return [Hash] JSON Schema for the tool's input parameters
     def self.input_schema
       {
         type: "object",
         properties: {
-          title: {type: "string", description: "Short, descriptive title for the feature request"},
-          description: {type: "string", description: "What you need and why — what were you trying to do, and what's missing?"}
+          title: {type: "string"},
+          description: {type: "string", description: "Use gh-issue skill for guidance."}
         },
         required: %w[title description]
       }

data/lib/tools/read.rb

@@ -16,17 +16,18 @@ module Tools
   #   tool.execute("path" => "large.log", "offset" => 2001, "limit" => 500)
   #   # => "line 2001 content\n..."
   class Read < Base
-    def self.tool_name = "read"
+    def self.tool_name = "read_file"
+    def self.truncation_threshold = nil
 
-    def self.description = "Read file contents. Returns plain text with smart truncation. Use offset/limit to page through large files."
+    def self.description = "Read file. Relative paths resolve against working directory."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
-          offset: {type: "integer", description: "1-indexed line number to start from (default: 1)"},
-          limit: {type: "integer", description: "Maximum lines to read (subject to line and byte caps from config)"}
+          path: {type: "string"},
+          offset: {type: "integer", description: "1-indexed line number (default: 1)."},
+          limit: {type: "integer", description: "Max lines to return."}
         },
         required: ["path"]
       }

data/lib/tools/recall.rb

@@ -0,0 +1,98 @@
+# 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}.
+  #
+  # Two-step memory workflow:
+  #   1. `recall(query: "auth flow")` → discovers relevant messages
+  #   2. `remember(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.
+  #
+  # @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"
+
+    def self.description = "Find messages across past conversations by keywords."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          query: {type: "string"},
+          session_only: {type: "boolean", description: "Default: all sessions"}
+        },
+        required: ["query"]
+      }
+    end
+
+    # @param session [Session] the current session (used for session_only scoping)
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # @param input [Hash] with "query" and optional "session_only"
+    # @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)
+
+      return "No results found for \"#{query}\"." if results.empty?
+
+      format_results(query, results)
+    end
+
+    private
+
+    # Formats results as token-efficient, LLM-readable output.
+    # Each result includes message_id for drill-down via remember tool.
+    #
+    # @param query [String] the original search query
+    # @param results [Array<Mneme::Search::Result>] ranked search results
+    # @return [String] formatted output
+    def format_results(query, results)
+      session_names = load_session_names(results)
+
+      result_word = (results.size == 1) ? "result" : "results"
+      lines = ["Found #{results.size} #{result_word} for \"#{query}\":", ""]
+      results.each { |result| lines.concat(format_single_result(result, session_names)) }
+      lines.join("\n")
+    end
+
+    # Formats a single search result as display lines.
+    #
+    # @param result [Mneme::Search::Result]
+    # @param session_names [Hash{Integer => String}]
+    # @return [Array<String>]
+    def format_single_result(result, session_names)
+      sid = result.session_id
+      session_name = session_names[sid] || "Session ##{sid}"
+      snippet = result.snippet.to_s.gsub(/\s+/, " ").strip
+
+      [
+        "[message #{result.message_id}, session \"#{session_name}\", #{result.message_type}]",
+        "  ...#{snippet}...",
+        ""
+      ]
+    end
+
+    # Batch-loads session names to avoid N+1 queries.
+    #
+    # @param results [Array<Mneme::Search::Result>]
+    # @return [Hash{Integer => String}] session_id => name
+    def load_session_names(results)
+      session_ids = results.map(&:session_id).uniq
+      Session.where(id: session_ids).pluck(:id, :name).to_h
+    end
+  end
+end

data/lib/tools/registry.rb

@@ -33,10 +33,14 @@ module Tools
     # @return [Array<Hash>] schema array for the Anthropic tools API parameter.
     #   Each schema includes an optional `timeout` parameter (seconds) injected
     #   by the registry. The agent can override the default per call for
-    #   long-running operations.
+    #   long-running operations. Tools with session-dependent schemas (e.g.
+    #   {Think} with budget-based maxLength, {Bash} with CWD in description)
+    #   are instantiated with context to generate their schema:
+    #   - {Think}: budget-based maxLength
+    #   - {Bash}: CWD embedded in description
     def schemas
       default = Anima::Settings.tool_timeout
-      @tools.values.map { |tool| inject_timeout(tool.schema, default) }
+      @tools.values.map { |tool| inject_timeout(resolve_schema(tool), default) }
     end
 
     # Execute a tool by name. Classes are instantiated with the registry's
@@ -53,6 +57,19 @@ module Tools
       instance.execute(input)
     end
 
+    # Returns the truncation threshold for a tool, or +nil+ if the tool
+    # opts out of truncation (e.g. read_file tool has its own pagination).
+    # MCP tools and other duck-typed instances use the default threshold.
+    #
+    # @param name [String] registered tool name
+    # @return [Integer, nil] character threshold, or nil to skip truncation
+    def truncation_threshold(name)
+      tool = @tools[name]
+      return tool.truncation_threshold if tool&.respond_to?(:truncation_threshold)
+
+      Anima::Settings.max_tool_response_chars
+    end
+
     # @param name [String] tool name to check
     # @return [Boolean] whether a tool with the given name is registered
     def registered?(name)
@@ -66,16 +83,28 @@ module Tools
 
     private
 
+    # Returns a tool's schema, preferring the instance-level dynamic
+    # variant when available. Only instantiates the tool when needed.
+    def resolve_schema(tool)
+      return tool.schema unless dynamic_schema?(tool)
+
+      tool.new(**@context).dynamic_schema
+    end
+
+    def dynamic_schema?(tool)
+      tool.is_a?(Class) && tool.method_defined?(:dynamic_schema)
+    end
+
     # Injects an optional `timeout` parameter into the tool's input schema.
     def inject_timeout(schema, default)
-      s = schema.deep_dup
-      s[:input_schema] ||= {type: "object", properties: {}}
-      s[:input_schema][:properties] ||= {}
-      s[:input_schema][:properties]["timeout"] = {
+      result = schema.deep_dup
+      input = result[:input_schema] ||= {type: "object", properties: {}}
+      props = input[:properties] ||= {}
+      props["timeout"] = {
         type: "integer",
-        description: "Max execution seconds (default: #{default}). Increase for long-running operations."
+        description: "Seconds (default: #{default})."
       }
-      s
+      result
     end
   end
 end