rubino-agent 0.3.0

data/install.sh

@@ -0,0 +1,275 @@
+#!/usr/bin/env bash
+#
+# rubino installer
+#
+#   curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install.sh | bash
+#
+# What it does (all in user space, no sudo):
+#   1. Provisions a Ruby toolchain:
+#        - Linux: via `rv` (https://github.com/spinel-coop/rv), a fast Ruby
+#          version manager that fetches a precompiled Ruby (no build step).
+#        - macOS: if Homebrew is present you're asked whether to use Homebrew
+#          (`brew install ruby`) or rv; if Homebrew is absent it uses rv directly.
+#   2. Installs the `rubino-agent` gem under that Ruby. If a published gem with
+#      the CLI isn't available yet, it falls back to building from this repo.
+#   3. Prints the exact PATH line for the `rubino` executable.
+#
+# Non-interactive override: set RUBINO_INSTALL_METHOD=brew|rv to skip the prompt.
+#
+# Security note: you are piping a script from the internet into a shell.
+# Review it first:  curl -fsSL <url> -o install.sh && less install.sh && bash install.sh
+#
+# Re-running is safe: every step is idempotent.
+
+set -euo pipefail
+
+# --- configuration ----------------------------------------------------------
+
+REPO_OWNER="Jhonnyr97"
+REPO_NAME="rubino-agent"
+REPO_URL="https://github.com/${REPO_OWNER}/${REPO_NAME}.git"
+REPO_RAW="https://raw.githubusercontent.com/${REPO_OWNER}/${REPO_NAME}/main"
+
+# Ruby to install via rv. Matches the gem's .ruby-version; the gem itself
+# requires >= 3.1.0, so any 3.1+ works, but we pin a known-good precompiled one.
+# (Homebrew installs its current `ruby` formula instead; the gem supports both.)
+RUBY_VERSION="${RUBINO_RUBY_VERSION:-3.3.3}"
+
+# The gem name on RubyGems (rubino-agent) vs. the executable it ships (rubino).
+GEM_NAME="rubino-agent"
+BIN_NAME="rubino"
+
+# Optional: brew | rv. When unset on macOS with Homebrew present, we prompt.
+INSTALL_METHOD="${RUBINO_INSTALL_METHOD:-}"
+
+# --- output helpers ---------------------------------------------------------
+
+if [ -t 1 ]; then
+  BOLD=$(printf '\033[1m'); GREEN=$(printf '\033[32m'); YELLOW=$(printf '\033[33m')
+  RED=$(printf '\033[31m'); DIM=$(printf '\033[2m'); RESET=$(printf '\033[0m')
+else
+  BOLD=""; GREEN=""; YELLOW=""; RED=""; DIM=""; RESET=""
+fi
+
+info()  { printf '%s==>%s %s\n' "$BOLD" "$RESET" "$*"; }
+ok()    { printf '%s==>%s %s\n' "$GREEN" "$RESET" "$*"; }
+warn()  { printf '%s==>%s %s\n' "$YELLOW" "$RESET" "$*" >&2; }
+die()   { printf '%serror:%s %s\n' "$RED" "$RESET" "$*" >&2; exit 1; }
+
+# --- preflight: OS / arch ---------------------------------------------------
+
+OS="$(uname -s)"
+ARCH="$(uname -m)"
+
+case "$OS" in
+  Linux)  PLATFORM="linux"  ;;
+  Darwin) PLATFORM="macos"  ;;
+  *)      die "unsupported OS: ${OS}. rubino's installer supports Linux and macOS (x86_64/arm64)." ;;
+esac
+
+case "$ARCH" in
+  x86_64|amd64)  ;;
+  aarch64|arm64) ;;
+  *) die "unsupported architecture: ${ARCH}. Supported: x86_64, arm64." ;;
+esac
+
+need() { command -v "$1" >/dev/null 2>&1 || die "required command not found: $1 (please install it and re-run)"; }
+need curl
+need uname
+
+# --- choose install method (macOS may use Homebrew or rv) -------------------
+
+# Decide how we get Ruby. Linux always uses rv. macOS: honor an explicit
+# RUBINO_INSTALL_METHOD; else if Homebrew is present, ask (when a terminal is
+# available); else fall back to rv. The prompt reads from /dev/tty so it works
+# even under `curl ... | bash`, where stdin is the script itself.
+choose_method() {
+  if [ "$PLATFORM" = "linux" ]; then
+    printf 'rv\n'; return 0
+  fi
+
+  case "$INSTALL_METHOD" in
+    brew) printf 'brew\n'; return 0 ;;
+    rv)   printf 'rv\n';   return 0 ;;
+    "")   ;;
+    *)    die "RUBINO_INSTALL_METHOD must be 'brew' or 'rv' (got '${INSTALL_METHOD}')." ;;
+  esac
+
+  if ! command -v brew >/dev/null 2>&1; then
+    # No Homebrew → rv directly, as requested.
+    printf 'rv\n'; return 0
+  fi
+
+  # Homebrew present. Ask, if we have a terminal to ask on.
+  if [ -r /dev/tty ] && [ -w /dev/tty ]; then
+    {
+      printf '\n%sHomebrew detected.%s How should Ruby be installed?\n' "$BOLD" "$RESET"
+      printf '  %s1)%s Homebrew   %s(brew install ruby)%s\n'            "$BOLD" "$RESET" "$DIM" "$RESET"
+      printf '  %s2)%s rv         %s(fast, self-contained, no Homebrew)%s\n' "$BOLD" "$RESET" "$DIM" "$RESET"
+      printf 'Choose %s[1/2]%s (default 1): ' "$BOLD" "$RESET"
+    } >/dev/tty
+    local ans=""
+    read -r ans </dev/tty || ans=""
+    case "$ans" in
+      2|rv|RV)   printf 'rv\n' ;;
+      ""|1|brew) printf 'brew\n' ;;
+      *)         printf 'brew\n' ;;
+    esac
+    return 0
+  fi
+
+  # Homebrew present but no terminal to prompt on → default to Homebrew
+  # (the native macOS expectation). Override with RUBINO_INSTALL_METHOD=rv.
+  warn "Homebrew detected but no interactive terminal; defaulting to Homebrew. Set RUBINO_INSTALL_METHOD=rv to use rv instead."
+  printf 'brew\n'
+}
+
+METHOD="$(choose_method)"
+
+# `rubyx <cmd...>` runs a command (gem/bundle/rake/ruby) under the Ruby we set
+# up, regardless of method. Each setup_* defines it plus RUBY_LABEL.
+rubyx() { die "internal: ruby toolchain not initialized"; }
+
+# --- ruby toolchain: rv -----------------------------------------------------
+
+setup_ruby_rv() {
+  # rv's installer (cargo-dist) drops the binary in $CARGO_HOME/bin or
+  # $HOME/.cargo/bin. We pass RV_NO_MODIFY_PATH=1 so it doesn't edit the user's
+  # shell rc, and locate the binary ourselves.
+  locate_rv() {
+    if command -v rv >/dev/null 2>&1; then command -v rv; return 0; fi
+    for d in "${CARGO_HOME:-}/bin" "$HOME/.cargo/bin" "$HOME/.local/bin"; do
+      [ -n "$d" ] && [ -x "$d/rv" ] && { printf '%s\n' "$d/rv"; return 0; }
+    done
+    return 1
+  }
+
+  local rv_bin
+  if rv_bin="$(locate_rv)"; then
+    ok "rv already installed: ${rv_bin}"
+  else
+    info "Installing rv (fast Ruby version manager)..."
+    RV_NO_MODIFY_PATH=1 curl -fsSL https://rv.dev/install | sh
+    rv_bin="$(locate_rv)" || die "rv install completed but the rv binary wasn't found on PATH or in ~/.cargo/bin."
+    ok "Installed rv: ${rv_bin}"
+  fi
+  export PATH="$(dirname "$rv_bin"):${PATH}"
+
+  info "Installing Ruby ${RUBY_VERSION} via rv (precompiled, no build step)..."
+  "$rv_bin" ruby install "${RUBY_VERSION}"          # idempotent
+  local ruby_bin
+  ruby_bin="$("$rv_bin" ruby find "${RUBY_VERSION}")"
+  [ -x "$ruby_bin" ] || die "rv reported Ruby ${RUBY_VERSION} installed but its ruby binary wasn't found."
+  RUBY_BIN_DIR="$(dirname "$ruby_bin")"
+  RUBY_LABEL="Ruby ${RUBY_VERSION} (rv)"
+
+  rubyx() { "$rv_bin" run --ruby "${RUBY_VERSION}" "$@"; }
+  ok "${RUBY_LABEL} ready: ${RUBY_BIN_DIR}"
+}
+
+# --- ruby toolchain: Homebrew ----------------------------------------------
+
+setup_ruby_brew() {
+  need brew
+  if brew list --formula ruby >/dev/null 2>&1; then
+    ok "Homebrew Ruby already installed."
+  else
+    info "Installing Ruby via Homebrew (brew install ruby)..."
+    brew install ruby || die "brew install ruby failed."
+  fi
+  local prefix
+  prefix="$(brew --prefix ruby 2>/dev/null)" || die "could not resolve 'brew --prefix ruby'."
+  RUBY_BIN_DIR="${prefix}/bin"
+  [ -x "${RUBY_BIN_DIR}/ruby" ] || die "Homebrew ruby not found at ${RUBY_BIN_DIR}."
+  local ver
+  ver="$("${RUBY_BIN_DIR}/ruby" -e 'print RUBY_VERSION' 2>/dev/null || echo '?')"
+  RUBY_LABEL="Ruby ${ver} (Homebrew)"
+
+  # Run gem/bundle/rake from Homebrew's keg-only ruby bin without relinking.
+  rubyx() { PATH="${RUBY_BIN_DIR}:${PATH}" "$@"; }
+  ok "${RUBY_LABEL} ready: ${RUBY_BIN_DIR}"
+}
+
+info "Detected ${OS} ${ARCH}. Installing rubino via ${METHOD}."
+
+case "$METHOD" in
+  rv)   setup_ruby_rv ;;
+  brew) setup_ruby_brew ;;
+  *)    die "internal: unknown method '${METHOD}'." ;;
+esac
+
+# Where gem-installed executables land for the chosen Ruby. `gem environment
+# gembindir` is correct for both rv and Homebrew; fall back to the ruby bin dir.
+GEM_BIN_DIR="$(rubyx gem environment gembindir 2>/dev/null | tail -n1)" || GEM_BIN_DIR=""
+[ -n "${GEM_BIN_DIR:-}" ] && [ -d "$GEM_BIN_DIR" ] || GEM_BIN_DIR="$RUBY_BIN_DIR"
+
+# --- install the rubino gem -------------------------------------------------
+
+gem_bin_present() { [ -x "${GEM_BIN_DIR}/${BIN_NAME}" ]; }
+
+install_published() {
+  info "Trying published gem: gem install ${GEM_NAME}..."
+  if rubyx gem install "${GEM_NAME}" >/dev/null 2>&1; then
+    if gem_bin_present; then
+      ok "Installed ${GEM_NAME} from RubyGems."
+      return 0
+    fi
+    warn "A '${GEM_NAME}' gem was installed but it doesn't provide the '${BIN_NAME}' CLI; building from source instead."
+    rubyx gem uninstall "${GEM_NAME}" -aIx >/dev/null 2>&1 || true
+  fi
+  return 1
+}
+
+install_from_git() {
+  warn "Building ${GEM_NAME} from ${REPO_URL} (the CLI gem isn't on RubyGems yet)."
+  need git
+  local work
+  work="$(mktemp -d)"
+  trap 'rm -rf "$work"' RETURN
+  git clone --depth 1 "$REPO_URL" "$work/${REPO_NAME}" >/dev/null 2>&1 \
+    || die "git clone of ${REPO_URL} failed."
+  (
+    cd "$work/${REPO_NAME}"
+    info "Resolving dependencies (bundle install)..."
+    rubyx bundle install >/dev/null 2>&1 || die "bundle install failed."
+    info "Building the gem (rake build)..."
+    rubyx rake build >/dev/null 2>&1 || die "rake build failed."
+    local pkg
+    pkg="$(ls -1 pkg/${GEM_NAME}-*.gem 2>/dev/null | head -n1)"
+    [ -n "$pkg" ] || die "rake build produced no gem in pkg/."
+    info "Installing ${pkg}..."
+    rubyx gem install "$pkg" >/dev/null 2>&1 || die "gem install of the built package failed."
+  )
+  gem_bin_present || die "built and installed ${GEM_NAME} but the '${BIN_NAME}' executable is missing."
+  ok "Installed ${GEM_NAME} from source."
+}
+
+if gem_bin_present; then
+  CURRENT_VER="$("${GEM_BIN_DIR}/${BIN_NAME}" version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -n1 || true)"
+  ok "${BIN_NAME} ${CURRENT_VER:+v$CURRENT_VER }is already installed (re-run safe)."
+elif ! install_published; then
+  install_from_git
+fi
+
+# --- PATH guidance + success ------------------------------------------------
+
+printf '\n'
+ok "rubino installed (${RUBY_LABEL})."
+printf '\n'
+
+if command -v "${BIN_NAME}" >/dev/null 2>&1 && [ "$(command -v "${BIN_NAME}")" = "${GEM_BIN_DIR}/${BIN_NAME}" ]; then
+  PATH_OK=1
+else
+  PATH_OK=0
+fi
+
+if [ "$PATH_OK" -ne 1 ]; then
+  printf '%sAdd this line to your shell profile%s (~/.bashrc, ~/.zshrc, ~/.profile):\n' "$BOLD" "$RESET"
+  printf '\n  %sexport PATH="%s:$PATH"%s\n\n' "$DIM" "${GEM_BIN_DIR}" "$RESET"
+  printf 'Then open a new shell (or run the export above) so %s%s%s is on your PATH.\n\n' "$BOLD" "${BIN_NAME}" "$RESET"
+fi
+
+printf '%sNext step:%s\n\n' "$BOLD" "$RESET"
+printf '  %s%s setup%s   %s# guided first-run: pick a provider, paste a key%s\n\n' "$GREEN" "${BIN_NAME}" "$RESET" "$DIM" "$RESET"
+
+printf 'Run: %s%s setup%s\n' "$BOLD" "${BIN_NAME}" "$RESET"

data/lib/rubino/active_skill.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rubino
+  # In-process switch holding the ONE skill the user has pinned active for the
+  # session (MVP: one at a time). Mirrors Rubino::Modes: a process-level slot,
+  # set via `/skills <name>` (the completion-dropdown picker) and cleared via
+  # `/skills none`. The active skill is force-loaded into the system prompt each
+  # turn (Context::PromptAssembler), so the model actually uses it — not just a
+  # cosmetic chip.
+  #
+  # Lives at the process level intentionally — alpha rule: no premature
+  # persistence. A fresh `rubino chat` boots with NO active skill; an explicit
+  # `/skills <name>` takes effect for the rest of that process. We can move it
+  # onto Session later if users want it sticky across restarts.
+  #
+  # The sentinel "none" (and the `✗ none` dropdown entry) clears the slot.
+  module ActiveSkill
+    # The dropdown/CLI sentinel that clears the active skill.
+    NONE = "none"
+
+    class << self
+      # The active skill name (String), or nil when none is pinned.
+      attr_reader :current
+
+      # Pins +name+ as the active skill. A nil/empty/"none" clears it. Returns
+      # the new value (the name String, or nil when cleared). The caller is
+      # responsible for validating the name against the registry BEFORE calling
+      # this — ActiveSkill is a dumb slot, like Modes.
+      def set(name)
+        normalized = name.to_s.strip
+        @current = normalized.empty? || normalized.casecmp?(NONE) ? nil : normalized
+      end
+
+      # Clears the active skill (the `/skills none` / `✗ none` path).
+      def clear
+        @current = nil
+      end
+
+      # True when a skill is pinned.
+      def active?
+        !@current.nil?
+      end
+
+      # Test/teardown hook. Not part of the public API.
+      def reset!
+        @current = nil
+      end
+    end
+  end
+end

data/lib/rubino/agent/agent_registry.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Registry of all defined agents (primary, sub, utility).
+    # Default agent system prompts are stored in agent/prompts/*.txt so they
+    # can be edited without modifying Ruby source.
+    class AgentRegistry
+      PROMPTS_DIR = File.expand_path("prompts", __dir__)
+
+      def initialize
+        @agents = {}
+        register_defaults!
+      end
+
+      # Returns all primary agents.
+      def primary_agents
+        @agents.values.select(&:primary?)
+      end
+
+      # Returns all visible subagents (for @mention).
+      def subagents
+        @agents.values.select { |a| a.subagent? && !a.hidden? }
+      end
+
+      # Returns all agents including hidden.
+      def all
+        @agents.values
+      end
+
+      # Finds an agent by name.
+      def find(name)
+        @agents[name.to_s]
+      end
+
+      # Registers a custom agent definition.
+      def register(definition)
+        @agents[definition.name] = definition
+      end
+
+      # Returns the default primary agent.
+      def default
+        find("build") || primary_agents.first
+      end
+
+      private
+
+      def register_defaults!
+        register(Definition.new(
+                   name: "build",
+                   type: :primary,
+                   description: "Full-access development agent with all tools",
+                   system_prompt: load_prompt("build"),
+                   tools: :all
+                 ))
+
+        register(Definition.new(
+                   name: "plan",
+                   type: :primary,
+                   description: "Read-only analysis and planning agent",
+                   system_prompt: load_prompt("plan"),
+                   tools: :read_only,
+                   permissions: { "edit *" => "ask", "shell *" => "ask" }
+                 ))
+
+        register(Definition.new(
+                   name: "explore",
+                   type: :subagent,
+                   description: "Fast read-only codebase exploration",
+                   system_prompt: load_prompt("explore"),
+                   tools: :read_only,
+                   max_turns: 20
+                 ))
+
+        register(Definition.new(
+                   name: "general",
+                   type: :subagent,
+                   description: "General-purpose agent for complex multi-step tasks",
+                   system_prompt: load_prompt("general"),
+                   tools: :all,
+                   max_turns: 50
+                 ))
+
+        register(Definition.new(
+                   name: "compaction",
+                   type: :utility,
+                   description: "Compresses long contexts",
+                   system_prompt: load_prompt("compaction"),
+                   hidden: true,
+                   tools: []
+                 ))
+
+        register(Definition.new(
+                   name: "title",
+                   type: :utility,
+                   description: "Generates session titles",
+                   system_prompt: "Generate a concise title (max 6 words) for this conversation based on the first user message.",
+                   hidden: true,
+                   tools: []
+                 ))
+      end
+
+      # Loads a prompt for a role. Checks the customer config for an
+      # explicit override first (prompts.overrides.<role>) and falls back
+      # to the built-in agent/prompts/<role>.txt. Missing files resolve
+      # to an empty string so a stripped-down distribution doesn't crash
+      # the registry at boot.
+      def load_prompt(name)
+        override = Rubino.configuration.prompts_override_for(name)
+        return override if override
+
+        path = File.join(PROMPTS_DIR, "#{name}.txt")
+        File.exist?(path) ? File.read(path).strip : ""
+      rescue StandardError
+        path = File.join(PROMPTS_DIR, "#{name}.txt")
+        File.exist?(path) ? File.read(path).strip : ""
+      end
+    end
+  end
+end

data/lib/rubino/agent/backoff_policy.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Jittered exponential backoff for retries, a faithful port of the
+    # reference jittered_backoff:
+    #
+    #   delay  = min(base * 2^(attempt-1), max)
+    #   result = delay + uniform(0, jitter_ratio * delay)   # jitter_ratio = 0.5
+    #
+    # Jitter decorrelates concurrent retries so multiple sessions hitting the
+    # same rate-limited provider don't all retry at the same instant.
+    #
+    # Deviation from the reference (intentional): the reference
+    # seeds a fresh RNG from a process-global monotonic counter + time on every
+    # call to stay decorrelated across threads with a coarse clock. We use
+    # Ruby's `rand`, whose Mersenne-Twister default RNG is already per-process
+    # and well-distributed — no global counter, no lock, less code. The
+    # decorrelation property (jitter spread over [0, 0.5*delay]) is preserved.
+    #
+    # Two presets mirror the conversation loop's two backoff sites:
+    #   * INVALID_RESPONSE — base 5s, cap 120s
+    #   * ERROR_PATH       — base 2s, cap  60s
+    class BackoffPolicy
+      JITTER_RATIO = 0.5
+
+      # Preset = [base_delay, max_delay] in seconds.
+      INVALID_RESPONSE = { base: 5.0, max: 120.0 }.freeze
+      ERROR_PATH       = { base: 2.0, max: 60.0 }.freeze
+
+      # Retry-After header values larger than this are clamped, matching the
+      # reference 2-minute cap.
+      RETRY_AFTER_CAP = 120.0
+
+      # cancel_token: an Interaction::CancelToken (or anything answering #check!)
+      # so a backoff wait aborts promptly on Ctrl+C instead of blocking for the
+      # full delay. Optional — nil means a plain (still sliced) sleep.
+      def initialize(cancel_token: nil)
+        @cancel_token = cancel_token
+      end
+
+      # Jittered delay in seconds for a 1-based attempt. `base`/`max` default to
+      # the error-path preset; pass a preset hash's values for the other site.
+      def jittered(attempt, base: ERROR_PATH[:base], max: ERROR_PATH[:max])
+        exponent = [0, attempt - 1].max
+        delay = base <= 0 || exponent >= 63 ? max : [base * (2**exponent), max].min
+        delay + (rand * JITTER_RATIO * delay)
+      end
+
+      # The wait to honour for a retry. When the upstream sent a Retry-After we
+      # respect it (clamped to RETRY_AFTER_CAP), exactly as the reference does on the
+      # rate-limited path; otherwise fall back
+      # to the jittered backoff.
+      def wait_seconds(attempt, base:, max:, retry_after: nil)
+        ra = parse_retry_after(retry_after)
+        return [ra, RETRY_AFTER_CAP].min if ra
+
+        jittered(attempt, base: base, max: max)
+      end
+
+      # Sleep `seconds`, sliced into 100ms ticks, polling the cancel token
+      # between ticks so Ctrl+C aborts within ~100ms instead of blocking the
+      # whole wait. On cancel, CancelToken#check! raises Interrupted. Mirrors
+      # the adapter's former cancellable_sleep and the reference incremental sleep
+      # loop.
+      def sleep(seconds)
+        deadline = monotonic_now + seconds
+        while (remaining = deadline - monotonic_now).positive?
+          @cancel_token&.check!
+          Kernel.sleep([0.1, remaining].min)
+        end
+      end
+
+      # Pull a Retry-After value from a raw header value (String/Numeric) or a
+      # typed error carrying a Faraday response. Returns Float seconds or nil.
+      #
+      # NOTE: only the delta-seconds form (e.g. "30") is parsed. The HTTP-date
+      # form of Retry-After is not handled — no provider this gem targets sends
+      # it, and the reference likewise only parses the numeric form. TODO: handle the
+      # date form if a provider ever needs it.
+      def parse_retry_after(value)
+        return if value.nil?
+
+        raw =
+          if value.is_a?(Numeric) || value.is_a?(String)
+            value
+          else
+            retry_after_header(value)
+          end
+        return if raw.nil?
+
+        f = Float(raw, exception: false)
+        f if f&.positive?
+      end
+
+      private
+
+      # Reach a Retry-After header off a typed error's Faraday response, if
+      # present. ruby_llm wraps the Faraday::Response on the error (#response),
+      # whose #headers is a case-insensitive hash. Returns nil when unreachable.
+      def retry_after_header(error)
+        return unless error.respond_to?(:response)
+
+        response = error.response
+        headers = response.respond_to?(:headers) ? response.headers : nil
+        return unless headers.respond_to?(:[])
+
+        headers["retry-after"] || headers["Retry-After"]
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/rubino/agent/definition.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Defines an agent type with its own model, system prompt, permissions, and tools.
+    # Agents can be primary (user-facing) or subagents (invokable by other agents).
+    class Definition
+      attr_reader :name, :type, :model, :system_prompt, :description,
+                  :permissions, :tools, :hidden
+
+      # Types: :primary (user-switchable), :subagent (invokable), :utility (hidden)
+      TYPES = %i[primary subagent utility].freeze
+
+      def initialize(attrs = {})
+        @name = attrs[:name]
+        @type = attrs[:type] || :primary
+        @model = attrs[:model]
+        @system_prompt = attrs[:system_prompt]
+        @description = attrs[:description] || ""
+        @permissions = attrs[:permissions] || {}
+        @mcp_servers = attrs[:mcp_servers] # :all or array of server names
+        @tools = attrs[:tools] || :all # :all, :read_only, or array of tool names
+        @hidden = attrs[:hidden] || false
+        @max_turns = attrs[:max_turns]
+      end
+
+      def primary?
+        @type == :primary
+      end
+
+      def subagent?
+        @type == :subagent
+      end
+
+      def utility?
+        @type == :utility
+      end
+
+      def hidden?
+        @hidden
+      end
+
+      # Which MCP servers this agent may use: :all, or an array of server
+      # names. An explicit value passed in code wins; otherwise the
+      # `agents.<name>.mcp_servers` block in config.yml applies (#92), and
+      # absent both the agent sees every server. YAML has no symbols, so the
+      # literal string "all" from config normalizes to :all — the value
+      # #resolved_tools compares against.
+      def mcp_servers
+        return @mcp_servers if @mcp_servers
+
+        configured = Rubino.configuration.dig("agents", name.to_s, "mcp_servers")
+        case configured
+        when Array then configured.map(&:to_s)
+        else :all
+        end
+      end
+
+      # Returns the max turns for this agent (falls back to global config)
+      def max_turns
+        @max_turns || Rubino.configuration.agent_max_turns
+      end
+
+      # Returns the resolved model (falls back to global default)
+      def resolved_model
+        @model || Rubino.configuration.model_default
+      end
+
+      # Returns tool list based on the agent's tool configuration.
+      #
+      # Scoped nesting (S1): a subagent now KEEPS the delegation tools (`task` and
+      # its companions `task_result`/`task_stop`) so it can spawn its own
+      # subagents. Runaway recursion / fan-out is no longer prevented by hiding
+      # the tool here — it is bounded in ONE place, Tools::BackgroundTasks#reserve,
+      # by the depth / per-owner / global caps. (DELEGATION_TOOLS is kept as a
+      # named set for any reader that still wants to reason about the group.)
+      DELEGATION_TOOLS = %w[task task_result task_stop].freeze
+
+      # Tools that ONLY make sense for a subagent and must be hidden from a
+      # primary/top-level agent. ask_parent escalates a question to the PARENT — a
+      # top-level agent has no parent, so exposing it there would be a dead tool.
+      # Subagents keep it; everyone else drops it. This is the single enforcement
+      # point and is UNCHANGED by S1 (re-enabling nesting does not expose
+      # ask_parent to top-level agents).
+      SUBAGENT_ONLY_TOOLS = %w[ask_parent].freeze
+
+      def resolved_tools
+        tools =
+          case @tools
+          when :all
+            Tools::Registry.enabled_tools
+          when :read_only
+            Tools::Registry.enabled_tools.select { |t| t.risk_level == :low }
+          when Array
+            @tools.filter_map { |name| Tools::Registry.find(name) }
+          else
+            Tools::Registry.enabled_tools
+          end
+
+        # Per-agent MCP scoping (#92/#173): every consumer of this agent's tool
+        # set (Lifecycle#load_tools, prompt assembler) goes through here, so
+        # filtering MCP wrappers HERE is what actually keeps an out-of-scope
+        # server's tools away from the model.
+        tools = reject_unscoped_mcp_tools(tools)
+
+        # ask_parent is subagent-only; a primary/top-level agent has no parent.
+        # Nesting is otherwise allowed for everyone — the delegation tools stay.
+        if subagent?
+          tools
+        else
+          tools.reject { |t| SUBAGENT_ONLY_TOOLS.include?(t.name) }
+        end
+      end
+
+      private
+
+      # Drops MCPToolWrapper instances whose server is not in this agent's
+      # mcp_servers allowlist (:all keeps everything). Built-in tools pass
+      # through untouched.
+      def reject_unscoped_mcp_tools(tools)
+        allowed = mcp_servers
+        return tools if allowed == :all
+
+        tools.reject { |t| t.is_a?(MCP::MCPToolWrapper) && !allowed.include?(t.server_name.to_s) }
+      end
+    end
+  end
+end