silas 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be0574c8a9c71366220b9be69d9f3d679a6c0a469d907bec1fb2a7d53436f6b3
-  data.tar.gz: 5ac2adcf62f854ec3a4b8206c0d9a19bd33bb3b631615e36bffed425757126ca
+  metadata.gz: e82a0a643fc11af7860df4d2633f6bf22b5f07626eecc2a572b6304924b20a9c
+  data.tar.gz: 1464c694a8c8813c0d700d151a482d1c72c901e3f6690464fcf30fc0e3185e01
 SHA512:
-  metadata.gz: 3a0be6b63aec608abe5cf2c72f0533c79b7150f8d389344a36e68c90122055fb1f304a4a251ade503467c875c21d99ddd9d136fa37f4d4734d1d5bda9c158bd6
-  data.tar.gz: 1340782f9cb00620e4e1ed5e9c5b9dc9fc8d96a9310d3d9e67e55004363352e4d17e98f62d1cb6054738b2fed1052c0c7e92f576f5afe587a33770db5294cc48
+  metadata.gz: 91d82c9f1fa784eb28cdffa635d8d04b97582d6b7201170bfc1052fcb036c43b89eab47462c6c931ca409e51595254f38cb56e336e74674bb30e3de69206e89e
+  data.tar.gz: c90cb14c3fd89d6bf8b605b0ec3a68e4d25255b6e82ea48a5d5f190cb6b59316182cc9228353aa71d4564c94c5871b022fea6be0035986fbf04e98c3696e3cf4

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 # 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
+  `canceled` immediately (pending approvals expire, so a late `approve!` can
+  never zombie-resume it); a running turn is flagged and honored at the next
+  step boundary, keeping the in-flight step's paid work. Engine-owned
+  (`:agent_sdk`) turns cancel only before the subprocess starts (v1). New
+  migration adds `silas_turns.cancel_requested_at`.
+- **Resumable budget parks.** A turn that hits `max_cost` / `max_input_tokens` /
+  `timeout` now PARKS at zero compute (state intact) instead of failing
+  terminally. A human resumes it with `turn.raise_budget!(max_cost: 1.50)` —
+  the top-up is recorded as a per-turn override and a fresh job replays
+  completed steps from rows (no model re-calls, no re-effects), continuing
+  where it left off. `bin/rails silas:chat` prompts for the top-up inline.
+  New migration adds `silas_turns.budget_overrides` (run
+  `bin/rails silas:install:migrations db:migrate` on upgrade). Notes: the
+  timeout clock includes time spent parked — size a timeout top-up from
+  elapsed wall-clock; budget parks have no TTL yet (visible in the inbox as
+  waiting); an inbox top-up card is planned.
+
 ## 0.1.4
 
 - **Fresh-app quickstart actually works.** A from-scratch install previously

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.
@@ -40,6 +54,16 @@ module Silas
 
       index = 0
       loop do
+        # Cancellation is honored at step boundaries only — the same safe point
+        # as budgets. (Mutable-state read between steps: benign, like the
+        # budget wall-clock check — a cancel landing later on resume is still
+        # a correct cancel.)
+        if turn.reload.cancel_requested_at
+          turn.expire_pending_approvals!("turn canceled")
+          turn.finish!(:canceled, reason: "canceled")
+          return
+        end
+
         step :"step_#{index}", isolated: isolate? do
           Ledger.assert_no_checkpoint!
           StepRunner.call(turn, index)
@@ -50,9 +74,12 @@ module Silas
         return if row.parked?
         break if row.terminal?
 
-        # Budget caps (cost/tokens/time) — checked between steps, never inside one.
+        # Budget caps (cost/tokens/time) — checked between steps, never inside
+        # one. A breach PARKS the turn (state intact, zero compute) rather than
+        # failing it: a human tops up with turn.raise_budget! and the fresh job
+        # replays completed steps from rows, resuming where it left off.
         if (reason = Budget.exceeded_reason(turn))
-          turn.finish!(:failed, reason: reason)
+          turn.update!(status: "waiting", failure_reason: reason)
           return
         end
 
@@ -79,6 +106,13 @@ module Silas
         Step.find_or_create_by!(turn: turn, index: 0) # anchor step exists before the MCP thread needs it
       end
 
+      # Cancellation for engine-owned turns is honored only BEFORE the
+      # subprocess starts — a running claude -p is not aborted mid-flight (v1).
+      if turn.reload.cancel_requested_at
+        turn.finish!(:canceled, reason: "canceled")
+        return
+      end
+
       outcome = nil
       step :run, isolated: isolate? do
         Ledger.assert_no_checkpoint!

data/app/models/silas/tool_invocation.rb

@@ -69,6 +69,7 @@ module Silas
     end
 
     def resume_turn!
+      return if turn.reload.canceled? # a canceled turn never zombie-resumes
       return if turn.tool_invocations.where(approval_state: "required").exists?
 
       turn.update!(status: "queued")

data/app/models/silas/turn.rb

@@ -24,6 +24,57 @@ module Silas
       update!(status: new_status.to_s, failure_reason: reason, finished_at: Time.current)
     end
 
+    def canceled? = status == "canceled"
+
+    # Cancel a turn. A PARKED or QUEUED turn (no live execution) settles to
+    # canceled immediately, expiring its pending approvals so a later approve!
+    # can't zombie-resume it. A RUNNING turn is flagged; the loop honors the
+    # flag at the next step boundary — the in-flight model call completes and
+    # its step commits (aborting mid-step would forfeit paid work and create
+    # an in-doubt tool window for nothing).
+    def cancel!(reason: "canceled")
+      raise Error, "turn #{id} is already terminal (#{status})" unless active?
+
+      if running?
+        update!(cancel_requested_at: Time.current)
+        :cancel_requested
+      else
+        expire_pending_approvals!(reason)
+        finish!(:canceled, reason: reason)
+        :canceled
+      end
+    end
+
+    def expire_pending_approvals!(reason)
+      tool_invocations.where(approval_state: "required").find_each do |inv|
+        inv.update!(approval_state: "expired", status: "failed",
+                    result: { "denied" => reason })
+      end
+    end
+
+    # Parked by a budget cap (failure_reason doubles as the park reason while
+    # the turn is waiting; it is cleared on resume).
+    def budget_parked?
+      waiting? && Budget::REASONS.include?(failure_reason)
+    end
+
+    # Human top-up for a budget-parked turn: record the raised limit(s) and
+    # resume with a fresh job — completed steps replay from rows, no model
+    # re-calls, no re-effects (the same resume path approvals use).
+    #   turn.raise_budget!(max_cost: 1.50)          # dollars
+    #   turn.raise_budget!(max_input_tokens: 200_000, timeout: 3600)
+    def raise_budget!(max_cost: nil, max_input_tokens: nil, timeout: nil)
+      raise Error, "turn #{id} is not budget-parked (#{status}/#{failure_reason})" unless budget_parked?
+
+      raises = { "max_cost" => max_cost, "max_input_tokens" => max_input_tokens,
+                 "timeout" => timeout }.compact
+      raise ArgumentError, "pass at least one limit to raise" if raises.empty?
+
+      update!(budget_overrides: (budget_overrides || {}).merge(raises),
+              failure_reason: nil, status: "queued")
+      AgentLoopJob.perform_later(id)
+    end
+
     # The agent's answer for this turn: the last completed step's text blocks.
     def answer_text
       step = steps.where(status: "completed").order(:index).last

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/db/migrate/20260716000001_add_budget_overrides_to_silas_turns.rb

@@ -0,0 +1,7 @@
+class AddBudgetOverridesToSilasTurns < ActiveRecord::Migration[8.1]
+  def change
+    # Per-turn budget raises (max_cost / max_input_tokens / timeout), set by a
+    # human topping up a budget-parked turn. Overrides agent.yml/config limits.
+    add_column :silas_turns, :budget_overrides, :json, null: false, default: {}
+  end
+end

data/db/migrate/20260716000002_add_cancel_requested_to_silas_turns.rb

@@ -0,0 +1,7 @@
+class AddCancelRequestedToSilasTurns < ActiveRecord::Migration[8.1]
+  def change
+    # Set by Turn#cancel! on a running turn; the loop honors it at the next
+    # step boundary (the same safe point budgets are checked at).
+    add_column :silas_turns, :cancel_requested_at, :datetime
+  end
+end

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/budget.rb

@@ -1,15 +1,21 @@
 module Silas
   # Per-turn budget caps beyond max_steps: cumulative input tokens, cost, and
   # wall-clock. Checked between steps in the framework-owned loop (never inside a
-  # continuation step), so a breach fails the turn cleanly with a limit reason.
+  # continuation step). A breach PARKS the turn at zero compute (like an
+  # approval); a human resumes it with Turn#raise_budget!, which records a
+  # per-turn override consulted here ahead of the agent's limits.
   #
   # Token/cost checks are deterministic (persisted step data). The timeout check
   # reads the wall clock — benign non-determinism: a cap firing later on resume
-  # is correct (the turn genuinely ran too long across the crash).
+  # is correct (the turn genuinely ran too long across the crash). Note the
+  # timeout clock includes time spent parked, so a timeout top-up should be
+  # sized from Time.current - started_at, not from the original limit.
   module Budget
+    REASONS = %w[max_input_tokens max_cost timeout].freeze
+
     module_function
 
-    # Returns a failure reason string if a cap is exceeded, else nil.
+    # Returns a limit-reason string if a cap is exceeded, else nil.
     def exceeded_reason(turn, agent: Silas.agent)
       return "max_input_tokens" if over_tokens?(turn, agent)
       return "max_cost" if over_cost?(turn, agent)
@@ -18,14 +24,20 @@ module Silas
       nil
     end
 
+    # A human top-up (turn.budget_overrides) beats the agent's configured limit.
+    def limit_for(turn, agent, key)
+      override = turn.budget_overrides&.dig(key.to_s)
+      override.nil? ? agent.public_send(key) : override
+    end
+
     def over_tokens?(turn, agent)
-      limit = agent.max_input_tokens or return false
+      limit = limit_for(turn, agent, :max_input_tokens) or return false
 
       Silas::Step.where(turn_id: turn.id).sum(:input_tokens) > limit
     end
 
     def over_cost?(turn, agent)
-      limit = agent.max_cost or return false
+      limit = limit_for(turn, agent, :max_cost) or return false
 
       spent = Silas::Inbox::Cost.for_turn(turn)
       # Only enforce on priced tokens; unpriced models can't be cost-capped.
@@ -33,7 +45,7 @@ module Silas
     end
 
     def over_time?(turn, agent)
-      limit = agent.timeout or return false
+      limit = limit_for(turn, agent, :timeout) or return false
       return false unless turn.started_at
 
       (Time.current - turn.started_at) > limit

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)
@@ -73,6 +79,7 @@ module Silas
 
       if turn.parked?
         settle_parked
+        settle_budget_park(turn.reload)
         turn.reload
       end
 
@@ -80,17 +87,40 @@ module Silas
     end
 
     def print_outcome(turn)
-      case turn.reload.status
+      turn.reload
+      case turn.status
       when "completed"
         @out.puts "agent> #{turn.answer_text}"
       when "waiting", "in_doubt"
-        @out.puts "(parked — #{pending_for(turn.session).count} approval(s) still pending; " \
-                  "they also render in /silas/inbox)"
+        if turn.budget_parked?
+          @out.puts "(parked: #{turn.failure_reason} budget reached — resume with " \
+                    "turn.raise_budget! or from a fresh silas:chat)"
+        else
+          @out.puts "(parked — #{pending_for(turn.session).count} approval(s) still pending; " \
+                    "they also render in /silas/inbox)"
+        end
       when "failed"
         @out.puts "(turn failed: #{turn.failure_reason})"
       end
     end
 
+    # A budget-parked turn prompts for a top-up right in the terminal. The
+    # resume runs synchronously on the :inline adapter, so new work (and
+    # possibly another park) follows immediately.
+    def settle_budget_park(turn)
+      return unless turn.budget_parked?
+
+      reason = turn.failure_reason
+      @out.puts "\nbudget reached — #{reason}"
+      @out.print "raise #{reason} to (blank to leave parked)> "
+      value = @in.gets&.strip
+      return if value.blank?
+
+      numeric = reason == "max_cost" ? value.to_f : value.to_i
+      turn.raise_budget!(**{ reason.to_sym => numeric })
+      print_trace(turn.reload)
+    end
+
     def print_trace(turn)
       ToolInvocation.where(turn_id: turn.id).order(:id).each do |inv|
         gate = inv.approval_state == "required" ? " — awaiting approval" : ""

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.4"
+  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.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Daniel St Paul
@@ -148,6 +148,8 @@ files:
 - db/migrate/20260715000001_add_channel_outbound_markers.rb
 - db/migrate/20260715000002_add_agent_sdk_columns_to_turns.rb
 - db/migrate/20260715000003_add_parent_session_to_silas_sessions.rb
+- db/migrate/20260716000001_add_budget_overrides_to_silas_turns.rb
+- db/migrate/20260716000002_add_cancel_requested_to_silas_turns.rb
 - lib/generators/silas/install/install_generator.rb
 - lib/generators/silas/install/templates/agent.yml
 - lib/generators/silas/install/templates/bin_ci
@@ -194,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