silas 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aa3f984d996b0eee69689f4009e3d43bd46d63caaf2144f0a4082b40d0ae918
-  data.tar.gz: 8c9b38ac7dae0a0ea510375046447442087a3a1536431199a8bf54677fca80b3
+  metadata.gz: e82a0a643fc11af7860df4d2633f6bf22b5f07626eecc2a572b6304924b20a9c
+  data.tar.gz: 1464c694a8c8813c0d700d151a482d1c72c901e3f6690464fcf30fc0e3185e01
 SHA512:
-  metadata.gz: f3136bfb1276a84217f76733e1c718715b8dbed5794fe766f72383cf58560c50950c6cdb12932d89108c6c6de73bd16b1c2c1b915841bb1829b47c102d03f0f5
-  data.tar.gz: 5af58996877a0bb1bf6d64fbf2ef30c141462c8d00a7f37ebbaaca4dbf3518cd28c4ead9557d4ee2d5a23144748632f053e38b908238b39c64577ce9f0d355fd
+  metadata.gz: 91d82c9f1fa784eb28cdffa635d8d04b97582d6b7201170bfc1052fcb036c43b89eab47462c6c931ca409e51595254f38cb56e336e74674bb30e3de69206e89e
+  data.tar.gz: c90cb14c3fd89d6bf8b605b0ec3a68e4d25255b6e82ea48a5d5f190cb6b59316182cc9228353aa71d4564c94c5871b022fea6be0035986fbf04e98c3696e3cf4

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.1.6
+
+- **Named agents — the staff pattern.** An app can now employ several
+  top-level agents: `app/agents/<name>/` (instructions.md, agent.yml, tools/,
+  skills/), autoloaded under `Agents::<Name>`, started with
+  `Silas.agent(:clerk).start(input: ...)`. Sessions are stamped with the
+  agent's name and **every turn — including crash resumes — runs under that
+  agent's own scope** (tools, skills, instructions, definitions digest), so a
+  rescued staff member can never wake up holding another agent's tools. The
+  inbox gains per-agent filter chips; `silas:chat` gains `AGENT=name`. The
+  root `app/agent` is unchanged and remains the default.
+- **Scope switching is now execution-isolated (concurrency fix).**
+  `with_agent_scope` previously mutated global config — two Solid Queue
+  threads running different agents (or a delegation racing a parallel job)
+  could see each other's tools. Scopes now live in
+  `ActiveSupport::IsolatedExecutionState` (per-thread *and* per-fiber —
+  Falcon-safe), nestable, with the readers (`Silas.agent`, `tool_resolver`,
+  `tool_definitions`, `skills`, `definitions_digest`, `instructions_dir`)
+  consulting the active scope first. This also fixes a latent bug where a
+  crashed *subagent* turn resumed by the rescuer would run under the ROOT
+  agent's scope.
+
+- **Approval lambdas get indifferent-access input.** Arguments are stored as
+  jsonb (string keys); a lambda writing `input[:amount]` got a silent nil —
+  fail-closed for gates written `nil > 50 ? park : approve`, but a silent
+  always-approve for the inverse. `input` is now
+  `ActiveSupport::HashWithIndifferentAccess`.
+- **Brownfield-safe installer.** `silas:install` now leaves an existing
+  `config/initializers/ruby_llm.rb` completely untouched (no conflict prompt —
+  an accidental Y clobbered production provider config). First generator specs.
+- **hermetic integration.** `config.sandbox = Hermetic.gvisor(image: ...)` is
+  now a documented, spec-covered path (the companion
+  [hermetic](https://github.com/danielstpaul/hermetic) gem: gVisor, Firecracker,
+  hosted E2B, or hardened Docker behind one `run` call, with `trust`/`off_host?`
+  as first-class axes). `sandbox_enabled?` now honors the configured backend's
+  own `enabled?` (a `Hermetic.null` won't advertise `run_code`), and configuring
+  a hermetic backend auto-arms its ledger guard — a sandbox exec inside a ledger
+  transaction fails loud. No new runtime dependency: Silas only duck-types
+  against the seam.
+
 ## 0.1.5
 
 - **Turn cancellation.** `turn.cancel!` — a parked or queued turn settles to

data/README.md

@@ -11,7 +11,9 @@ the durable stack is already booted inside your app. The only new surface is the
 Honestly early and honestly narrow: **v0.1, one maintainer, zero external
 users**, durability proven by an in-repo `kill -9` chaos harness (100/100, zero
 duplicate effects, byte-identical replay), and scoped to **trusted code you write
-yourself** (the sandbox is an interim Docker seam, not a microVM). The full pitch
+yourself** by default — for untrusted or model-generated code, drop in the
+companion gem [hermetic](https://github.com/danielstpaul/hermetic) (gVisor /
+Firecracker / hosted sandboxes behind one call, see below). The full pitch
 and the honest caveats: [Why Silas](docs/why-silas.md) ·
 [Silas vs eve](docs/vs-eve.md).
 
@@ -108,6 +110,56 @@ Inference is one pluggable seam (`config.engine`):
   in api_key mode). v1 is honestly weaker than `:ruby_llm`: exactly-once *within*
   a run, `approval :never` tools only, and fail-closed on a mid-subprocess kill.
 
+## Sandbox: run untrusted code with hermetic
+
+The sandbox is a second pluggable seam (`config.sandbox`). Built-in adapters are
+`:none` (default — code execution off) and `:docker` (hardened container,
+honest-but-interim). For real isolation, the companion gem
+[**hermetic**](https://github.com/danielstpaul/hermetic) drops straight in:
+
+```ruby
+# Gemfile: gem "hermetic"   (zero runtime deps)
+Silas.configure do |c|
+  c.sandbox = Hermetic.gvisor(image: "python:3.12-slim")     # or .docker /
+  # .firecracker(kernel:, rootfs:) / .hosted(:e2b, api_key:) # pick your strength
+end
+```
+
+That's the whole integration. When a sandbox is configured and enabled, the
+`run_code` tool is advertised to the model automatically (`at_most_once!` — an
+exec is an external effect). Two properties carry through the seam:
+
+- **The trust axis is visible**: every hermetic backend exposes `trust`
+  (`:vendor`/`:remote`/`:vm`/`:host`) and `off_host?`, so you can refuse to run
+  untrusted code on the box that holds your `RAILS_MASTER_KEY` — pair any local
+  backend with `executor:` to push execution to a dedicated sandbox host.
+- **The ledger guard is auto-armed**: configuring a hermetic backend loads its
+  Silas shim, so a sandbox exec attempted inside a ledger transaction fails loud
+  (sandbox-backed tools must be `at_most_once!`, never `transactional!`).
+
+## Named agents: the staff pattern
+
+One app can employ several agents, each with its own room:
+
+```
+app/agents/
+  reader/            # Silas.agent(:reader).start(input: "...")
+    instructions.md
+    agent.yml        # model, limits — same keys as the root agent
+    tools/
+    skills/
+  clerk/
+    ...
+```
+
+Sessions are stamped with the agent's name; every turn — including crash
+resumes — runs under that agent's own tools, skills, instructions, and
+definitions digest. The inbox filters by agent; `bin/rails silas:chat
+AGENT=clerk` chats with one staff member. The root `app/agent/` remains the
+default agent, unchanged. (Subagents stay a root-agent delegation feature;
+scope switching is execution-isolated, so concurrent jobs running different
+agents never cross wires.)
+
 ## Triggers
 
 An agent is reached by more than a method call:

data/app/controllers/silas/inbox/sessions_controller.rb

@@ -3,6 +3,8 @@ module Silas
     class SessionsController < BaseController
       def index
         @sessions = Silas::Session.order(created_at: :desc).limit(100)
+        @sessions = @sessions.where(agent_name: params[:agent]) if params[:agent].present?
+        @agent_names = Silas::Session.distinct.pluck(:agent_name).sort
         @pending_total = Silas::ToolInvocation.where(approval_state: "required").count
       end
 

data/app/jobs/silas/agent_loop_job.rb

@@ -20,6 +20,21 @@ module Silas
       turn = Turn.find(turn_id)
       return if turn.completed? || %w[failed canceled].include?(turn.status)
 
+      # Named-agent / subagent sessions run EVERY turn under their own scope
+      # (tools, skills, instructions, digest) — including resumes: a rescued
+      # turn re-enters here and re-establishes the same scope, so a crashed
+      # staff member never wakes up holding the root agent's tools.
+      scope = Silas.scope_for_session(turn.session)
+      if scope
+        Silas.with_agent_scope(scope) { drive(turn) }
+      else
+        drive(turn)
+      end
+    end
+
+    private
+
+    def drive(turn)
       if Silas.resolved_engine.class.loop_ownership == :engine
         perform_engine_owned(turn)
       else
@@ -27,7 +42,6 @@ module Silas
       end
     end
 
-    private
 
     # :ruby_llm — the framework drives the loop, one model call per step, tools
     # executed through the Ledger. The determinism constraints live here.

data/app/views/layouts/silas/inbox.html.erb

@@ -75,6 +75,10 @@
     .cost { font-family: var(--mono); font-size: 12px; color: var(--muted); }
     .flash { background: var(--red-bg); color: var(--red); padding: 10px 12px; border-radius: 10px; margin-bottom: 12px; }
     .empty { text-align: center; color: var(--muted); padding: 48px 0; }
+    .agent-filter { display: flex; gap: 6px; flex-wrap: wrap; margin-bottom: 14px; }
+    .agent-filter .chip { font-size: 12px; padding: 3px 10px; border: 1px solid #d9dce1;
+      border-radius: 999px; text-decoration: none; color: inherit; }
+    .agent-filter .chip-on { background: #16181d; color: #fff; border-color: #16181d; }
   </style>
 </head>
 <body>

data/app/views/silas/inbox/sessions/index.html.erb

@@ -2,6 +2,16 @@
   <% if @pending_total.positive? %><span class="badge"><%= @pending_total %> awaiting approval</span><% end %>
 <% end %>
 
+<% if @agent_names && @agent_names.size > 1 %>
+  <div class="agent-filter">
+    <%= link_to "all", inbox_sessions_path, class: params[:agent].blank? ? "chip chip-on" : "chip" %>
+    <% @agent_names.each do |name| %>
+      <%= link_to name, inbox_sessions_path(agent: name),
+            class: params[:agent] == name ? "chip chip-on" : "chip" %>
+    <% end %>
+  </div>
+<% end %>
+
 <% if @sessions.empty? %>
   <div class="empty">No agent sessions yet.</div>
 <% else %>

data/lib/generators/silas/install/install_generator.rb

@@ -8,8 +8,15 @@ module Silas
       def create_initializer
         template "initializer.rb", "config/initializers/silas.rb"
         # ruby_llm reads no provider keys from ENV on its own; without this the
-        # first model call raises ConfigurationError.
-        template "ruby_llm.rb", "config/initializers/ruby_llm.rb"
+        # first model call raises ConfigurationError. Brownfield apps often
+        # already configure ruby_llm themselves — never touch an existing one
+        # (not even a conflict prompt: an accidental Y clobbers production
+        # provider config).
+        if File.exist?(File.join(destination_root, "config/initializers/ruby_llm.rb"))
+          say_status :skip, "config/initializers/ruby_llm.rb exists — left untouched", :yellow
+        else
+          template "ruby_llm.rb", "config/initializers/ruby_llm.rb"
+        end
       end
 
       def create_agent_directory

data/lib/silas/chat.rb

@@ -43,9 +43,15 @@ module Silas
 
     private
 
+    # AGENT=clerk resumes/starts against a named agent (app/agents/clerk/).
+    def agent_handle
+      @agent_handle ||= ENV["AGENT"].present? ? Silas.agent(ENV["AGENT"]) : Silas.agent
+    end
+
     def banner
-      description = Silas.agent.description.presence || "your agent"
-      @out.puts "Silas chat — #{description} (#{Silas.agent.model})."
+      description = agent_handle.description.presence || "your agent"
+      label = ENV["AGENT"].present? ? "#{ENV['AGENT']} — " : ""
+      @out.puts "Silas chat — #{label}#{description} (#{agent_handle.model})."
       @out.puts "Approvals prompt inline. 'exit' or Ctrl-D to quit."
       @out.puts "Resuming session #{@session.id} (#{@session.turns.count} turns)." if @session
     end
@@ -53,7 +59,7 @@ module Silas
     def submit(text)
       turn =
         if @session.nil?
-          @session = Silas.agent.start(input: text)
+          @session = agent_handle.start(input: text)
           @session.turns.first
         else
           @session.continue(input: text)

data/lib/silas/configuration.rb

@@ -26,6 +26,9 @@ module Silas
     # Subagents: the roster (name+description) and per-name scope builders, plus
     # the active-agent overrides swapped in during a nested run.
     attr_accessor :subagent_index, :subagent_scopes, :agent_override, :instructions_dir
+
+    # Named top-level agents (app/agents/<name>/): lambda -> { name => AgentScope }.
+    attr_accessor :named_agent_scopes
     # Channels: name -> Channel subclass (wired by the Registry). Slack creds
     # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
     attr_accessor :channel_resolver

data/lib/silas/engine.rb

@@ -9,17 +9,28 @@ module Silas
     # Agent::Tools::IssueRefund. Tool identity remains the filename.
     initializer "silas.agent_directory" do |app|
       agent_dir = app.root.join("app/agent")
-      next unless agent_dir.exist?
+      if agent_dir.exist?
+        unless defined?(::Agent)
+          Object.const_set(:Agent, Module.new)
+        end
+        app.autoloaders.main.push_dir(agent_dir, namespace: ::Agent)
 
-      unless defined?(::Agent)
-        Object.const_set(:Agent, Module.new)
+        # Markdown/YAML (instructions.md, agent.yml, skills/*.md) are not Ruby;
+        # keep Zeitwerk away from them. tools/, schedules/ (.rb handlers), and
+        # channels/ all autoload under the Agent namespace via push_dir above.
+        app.autoloaders.main.ignore(agent_dir.join("skills"))
       end
-      app.autoloaders.main.push_dir(agent_dir, namespace: ::Agent)
 
-      # Markdown/YAML (instructions.md, agent.yml, skills/*.md) are not Ruby;
-      # keep Zeitwerk away from them. tools/, schedules/ (.rb handlers), and
-      # channels/ all autoload under the Agent namespace via push_dir above.
-      app.autoloaders.main.ignore(agent_dir.join("skills"))
+      # Named agents: app/agents/<name>/tools/x.rb autoloads as
+      # Agents::<Name>::Tools::X — the staff pattern.
+      agents_dir = app.root.join("app/agents")
+      if agents_dir.exist?
+        unless defined?(::Agents)
+          Object.const_set(:Agents, Module.new)
+        end
+        app.autoloaders.main.push_dir(agents_dir, namespace: ::Agents)
+        Dir[agents_dir.join("*/skills")].each { |d| app.autoloaders.main.ignore(d) }
+      end
     end
 
     initializer "silas.boot_guard", after: :load_config_initializers do
@@ -28,7 +39,7 @@ module Silas
 
     # Registry rebuilds on every code reload in development, once in production.
     initializer "silas.registry" do |app|
-      next unless app.root.join("app/agent").exist?
+      next unless app.root.join("app/agent").exist? || app.root.join("app/agents").exist?
 
       app.config.to_prepare { Silas::Registry.install!(root: Rails.root) }
     end

data/lib/silas/instructions.rb

@@ -12,7 +12,7 @@ module Silas
 
       turn.update!(
         instructions_snapshot: render(turn),
-        definitions_digest: Silas.config.definitions_digest&.call.to_s
+        definitions_digest: Silas.definitions_digest.to_s
       )
     end
 
@@ -24,7 +24,7 @@ module Silas
     def base_instructions(turn)
       # config.instructions_dir points at the active agent's directory (root or a
       # subagent, swapped during a nested run).
-      dir = Silas.config.instructions_dir || Rails.root.join("app/agent")
+      dir = Silas.instructions_dir || Rails.root.join("app/agent")
       path = Pathname(dir).join("instructions.md")
       return default_instructions unless path.exist?
 

data/lib/silas/ledger.rb

@@ -148,7 +148,10 @@ module Silas
         when :once
           previously_approved?(invocation) ? :approved : :user_approval
         when Proc
-          policy.call(session: invocation.turn.session, input: invocation.arguments)
+          # Indifferent access: arguments are stored as jsonb (string keys),
+          # but a lambda writing input[:amount] must not get a silent nil.
+          policy.call(session: invocation.turn.session,
+                      input: invocation.arguments.with_indifferent_access)
         else
           :not_applicable
         end

data/lib/silas/named_agent.rb

@@ -0,0 +1,32 @@
+module Silas
+  # Handle for a named top-level agent (app/agents/<name>/). Same surface as
+  # the root Agent — #start plus the definition readers — so call sites don't
+  # care which kind they hold. The only difference: sessions it starts are
+  # stamped with the agent's name, and the loop swaps in the agent's scope
+  # (tools, skills, instructions, digest) for every turn of those sessions.
+  class NamedAgent
+    attr_reader :scope
+
+    def initialize(scope)
+      @scope = scope
+    end
+
+    def name = scope.name
+
+    def start(input:, metadata: {}, channel: nil, continuation_token: nil)
+      session = Session.create!(agent_name: name, metadata: metadata,
+                                channel: channel, continuation_token: continuation_token)
+      session.continue(input: input)
+      session
+    end
+
+    # Definition readers delegate to the scope's parsed agent.yml.
+    def model       = scope.agent.model
+    def description = scope.agent.description
+    def limits      = scope.agent.limits
+    def max_steps   = scope.agent.max_steps
+    def max_input_tokens = scope.agent.max_input_tokens
+    def max_cost    = scope.agent.max_cost
+    def timeout     = scope.agent.timeout
+  end
+end

data/lib/silas/registry.rb

@@ -16,6 +16,7 @@ module Silas
       Silas.config.channel_resolver = ->(name) { registry.channels[name] }
       Silas.config.subagent_index = -> { registry.subagent_index }
       Silas.config.subagent_scopes = -> { registry.subagent_scopes }
+      Silas.config.named_agent_scopes = -> { registry.named_agent_scopes }
       Silas.config.agent_override = nil
       Silas.config.instructions_dir = nil
       Silas.reset_agent_memo!
@@ -103,6 +104,31 @@ module Silas
       }))
     end
 
+    # --- named agents (app/agents/<name>/ — the staff pattern) ---------------
+
+    RESERVED_AGENT_NAMES = %w[agent shared].freeze
+
+    def named_agent_dirs
+      @named_agent_dirs ||= Dir[@root.join("app/agents/*")].select { |p| File.directory?(p) }.sort
+    end
+
+    # { "clerk" => AgentScope, ... }. Each named agent is a full top-level
+    # agent: its own instructions.md, agent.yml, tools/, skills/ — autoloaded
+    # under Agents::<Camelized>. Sessions stamped with the name run every turn
+    # under this scope (loop-enforced, resume-safe, thread-isolated).
+    def named_agent_scopes
+      @named_agent_scopes ||= named_agent_dirs.to_h do |dir|
+        name = File.basename(dir)
+        if RESERVED_AGENT_NAMES.include?(name)
+          raise Error, "app/agents/#{name} collides with a reserved name — " \
+                       "'agent' is the root app/agent; rename the directory"
+        end
+
+        [ name, build_agent_scope(Pathname(dir), name, const_base: "Agents::#{name.camelize}",
+                                                       run_code: Silas.sandbox_enabled?) ]
+      end
+    end
+
     # --- subagents -----------------------------------------------------------
 
     def subagent_dirs
@@ -133,7 +159,15 @@ module Silas
     end
 
     def build_subagent_scope(dir, name)
-      const_base = "Agent::Subagents::#{name.camelize}"
+      build_agent_scope(dir, name, const_base: "Agent::Subagents::#{name.camelize}",
+                                   agent: subagent_agent(dir, name))
+    end
+
+    # Shared scope builder for subagents and named agents: tools by filename
+    # identity under const_base, skills, the load_skill builtin when skills
+    # exist, run_code when asked, and the scope's own digest (the same
+    # NondeterminismError guard root turns get).
+    def build_agent_scope(dir, name, const_base:, agent: nil, run_code: false)
       tools = Dir[dir.join("tools/*.rb")].sort.to_h do |file|
         tname = File.basename(file, ".rb")
         klass = "#{const_base}::Tools::#{tname.camelize}".constantize
@@ -143,12 +177,14 @@ module Silas
         [ tname, klass ]
       end
       skills = Dir[dir.join("skills/*.md")].sort.map { |f| Skill.parse(f) }
-      builtins = skills.any? ? { "load_skill" => Silas::Tools::LoadSkill } : {}
+      builtins = {}
+      builtins["load_skill"] = Silas::Tools::LoadSkill if skills.any?
+      builtins["run_code"] = Silas::Tools::RunCode if run_code
       resolver = ->(n) { (tools[n] || builtins.fetch(n)).new }
       definitions = (tools.values + builtins.values).map(&:schema)
       digest = Digest::SHA256.hexdigest(JSON.generate(tools: definitions, skills: skills.map { |s| [ s.name, s.description ] }))
 
-      Silas::AgentScope.new(name: name, dir: dir, agent: subagent_agent(dir, name),
+      Silas::AgentScope.new(name: name, dir: dir, agent: agent || Silas::Agent.load(dir: dir),
                             resolver: resolver, definitions: definitions, digest: digest, skills: skills)
     end
   end

data/lib/silas/step_runner.rb

@@ -70,9 +70,9 @@ module Silas
     # A deploy that changes tools/skills mid-turn must fail loudly, never
     # resume into a different agent than the one that started the turn.
     def assert_definitions_unchanged!(turn)
-      return if turn.definitions_digest.blank? || Silas.config.definitions_digest.nil?
+      return if turn.definitions_digest.blank? || Silas.definitions_digest.nil?
 
-      live = Silas.config.definitions_digest.call.to_s
+      live = Silas.definitions_digest.to_s
       return if live == turn.definitions_digest
 
       turn.finish!(:failed, reason: "definitions_changed")

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/lib/silas.rb

@@ -12,6 +12,7 @@ require "silas/skill"
 require "silas/schedule"
 require "silas/schedule/compiler"
 require "silas/agent_scope"
+require "silas/named_agent"
 require "silas/tools/delegate"
 require "silas/nested_runner"
 require "silas/sandbox"
@@ -62,7 +63,13 @@ module Silas
       @agent = nil
     end
 
-    def sandbox_enabled? = ![ :none, nil ].include?(config.sandbox)
+    # A configured-but-disabled backend (e.g. Hermetic.null) must not register
+    # run_code, so the object's own enabled? is the final word.
+    def sandbox_enabled?
+      return false if [ :none, nil ].include?(config.sandbox)
+
+      resolved_sandbox.enabled?
+    end
 
     def resolved_sandbox
       @resolved_sandbox ||=
@@ -74,7 +81,14 @@ module Silas
                               pids: config.sandbox_pids, workdir: config.sandbox_workdir,
                               docker_bin: config.sandbox_docker_bin)
         when Symbol then raise Error, "unknown sandbox #{config.sandbox.inspect}"
-        else config.sandbox
+        else
+          # A hermetic backend drops straight in (its Result is a superset of
+          # ours). Auto-arm its ledger guard so a sandbox exec inside a ledger
+          # transaction fails loud — same posture as our own Docker adapter.
+          if defined?(Hermetic::Backends::Base) && config.sandbox.is_a?(Hermetic::Backends::Base)
+            require "hermetic/silas"
+          end
+          config.sandbox
         end
     end
 
@@ -92,26 +106,60 @@ module Silas
         end
     end
 
+    # ---- scope-aware readers -------------------------------------------------
+    # Every reader consults the active AgentScope first (named agent or
+    # subagent), falling back to the boot-time config the Registry installed.
+    # The scope lives in IsolatedExecutionState — per-thread AND per-fiber
+    # (Falcon-safe), so concurrent jobs running different agents in one
+    # process can never see each other's tools.
+
     def tool_resolver
-      config.tool_resolver or raise Error, "no tool resolver configured (Registry boots one; specs must inject)"
+      current_scope&.resolver ||
+        config.tool_resolver or raise Error, "no tool resolver configured (Registry boots one; specs must inject)"
     end
 
     def tool_definitions
-      config.tool_definitions&.call || []
+      current_scope&.definitions || config.tool_definitions&.call || []
     end
 
     def skills
-      config.skills&.call || []
+      current_scope&.skills || config.skills&.call || []
     end
 
     def schedules
       config.schedules&.call || []
     end
 
-    # The active agent definition. config.agent_override is set during a nested
-    # subagent run; otherwise it's the root app/agent.
-    def agent
-      config.agent_override || (@agent ||= Agent.load)
+    # The live definitions digest as a String (nil when none configured).
+    def definitions_digest
+      current_scope&.digest || config.definitions_digest&.call&.to_s.presence
+    end
+
+    def instructions_dir
+      current_scope&.dir || config.instructions_dir
+    end
+
+    # The active agent definition — or, given a name, a handle for a NAMED
+    # agent (app/agents/<name>/) whose sessions run under that agent's scope:
+    #
+    #   Silas.agent.start(input: "...")            # the root app/agent
+    #   Silas.agent(:clerk).start(input: "...")    # a named staff member
+    def agent(name = nil)
+      return NamedAgent.new(named_agent_scope!(name)) if name
+
+      current_scope&.agent || config.agent_override || (@agent ||= Agent.load)
+    end
+
+    # Named-agent roster: { "name" => AgentScope }.
+    def named_agent_scopes = config.named_agent_scopes&.call || {}
+    def named_agent?(name) = named_agent_scopes.key?(name.to_s)
+
+    def named_agent_scope!(name)
+      named_agent_scopes.fetch(name.to_s) do
+        known = named_agent_scopes.keys
+        raise Error, "unknown agent #{name.inspect}" \
+                     "#{known.any? ? " (known: #{known.join(', ')})" : " — no app/agents/ directories found"}"
+      end
     end
 
     # Subagent roster: [[name, description], ...] (model-visible, so it's in the
@@ -120,24 +168,36 @@ module Silas
     def subagent?(name) = subagent_index.any? { |n, _| n == name.to_s }
     def subagent_scope(name) = config.subagent_scopes&.call&.fetch(name.to_s)
 
-    # Run a block with a subagent's scope swapped in as the active globals,
-    # restoring afterward. Synchronous/depth-1 — safe because delegation runs
-    # inline on one thread while the parent loop is paused in the delegate tool.
+    # The scope a session's turns must run under: nil for the root agent,
+    # otherwise the named-agent or subagent scope matching session.agent_name.
+    # Fails loud on an unknown name — a session pointing at a deleted agent
+    # directory must never silently run with the root agent's tools.
+    def scope_for_session(session)
+      name = session.agent_name.to_s
+      return nil if name.empty? || name == "agent"
+
+      named_agent_scopes[name] || config.subagent_scopes&.call&.[](name) or
+        raise Error, "session #{session.id} belongs to agent #{name.inspect}, " \
+                     "but no app/agents/#{name} or app/agent/subagents/#{name} exists"
+    end
+
+    # ---- scope switching -----------------------------------------------------
+
+    SCOPE_KEY = :silas_agent_scope
+
+    def current_scope
+      ActiveSupport::IsolatedExecutionState[SCOPE_KEY]
+    end
+
+    # Run a block under an AgentScope. Nestable (delegation inside a named
+    # agent restores the outer scope on exit) and isolated per execution
+    # context — no global config is mutated, so concurrent jobs are safe.
     def with_agent_scope(scope)
-      saved = {
-        tool_resolver: config.tool_resolver, tool_definitions: config.tool_definitions,
-        definitions_digest: config.definitions_digest, skills: config.skills,
-        agent_override: config.agent_override, instructions_dir: config.instructions_dir
-      }
-      config.tool_resolver = scope.resolver
-      config.tool_definitions = -> { scope.definitions }
-      config.definitions_digest = -> { scope.digest }
-      config.skills = -> { scope.skills }
-      config.agent_override = scope.agent
-      config.instructions_dir = scope.dir
+      previous = ActiveSupport::IsolatedExecutionState[SCOPE_KEY]
+      ActiveSupport::IsolatedExecutionState[SCOPE_KEY] = scope
       yield
     ensure
-      saved.each { |k, v| config.public_send("#{k}=", v) }
+      ActiveSupport::IsolatedExecutionState[SCOPE_KEY] = previous
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Daniel St Paul
@@ -196,6 +196,7 @@ files:
 - lib/silas/mcp/handler.rb
 - lib/silas/mcp/server.rb
 - lib/silas/message_builder.rb
+- lib/silas/named_agent.rb
 - lib/silas/nested_runner.rb
 - lib/silas/registry.rb
 - lib/silas/sandbox.rb