silas 0.1.7 → 0.2.0

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

@@ -53,23 +53,41 @@ module Silas
         end
       end
 
+      RESCUER_ENTRY = <<~YAML.freeze
+        # Silas: retries jobs failed by dead-worker reaping/pruning, sweeps
+        # expired approvals, and fails turns stranded by dead loop jobs. Part
+        # of the durability contract — do not remove.
+        silas_dead_job_rescuer:
+          class: Silas::DeadJobRescuerJob
+          queue: default
+          schedule: every 30 seconds
+      YAML
+
+      # Idempotent and environment-aware: the entry is injected directly under
+      # EVERY deployable top-level env key (production, staging, …) — never a
+      # blind append into whatever block happens to end the file, and never a
+      # duplicate key on a re-run. A staging worker needs the rescuer exactly
+      # as much as production does.
       def add_rescuer_recurring_task
         recurring = "config/recurring.yml"
-        entry = <<~YAML
+        path = File.expand_path(recurring, destination_root)
 
-          # Silas: retries jobs failed by dead-worker reaping/pruning and sweeps
-          # expired approvals. Part of the durability contract — do not remove.
-          silas_dead_job_rescuer:
-            class: Silas::DeadJobRescuerJob
-            queue: default
-            schedule: every 30 seconds
-        YAML
+        unless File.exist?(path)
+          create_file recurring, "production:\n#{RESCUER_ENTRY.indent(2)}"
+          return
+        end
 
-        if File.exist?(File.expand_path(recurring, destination_root))
-          append_to_file recurring, entry.indent(2)
-        else
-          create_file recurring, "production:#{entry.indent(2)}"
+        if File.read(path).include?("silas_dead_job_rescuer")
+          say_status :skip, "#{recurring} already contains silas_dead_job_rescuer", :yellow
+          return
+        end
+
+        injected = false
+        gsub_file recurring, /^(?!development:|test:)([a-zA-Z_]+:)[ \t]*$/ do |header|
+          injected = true
+          "#{header}\n#{RESCUER_ENTRY.indent(2)}"
         end
+        append_to_file recurring, "\nproduction:\n#{RESCUER_ENTRY.indent(2)}" unless injected
       end
 
       def install_migrations
@@ -91,8 +109,9 @@ module Silas
             7. Channels (optional): set credentials.silas.slack.{signing_secret,bot_token}
                for Slack; route inbound mail to Silas::AgentMailbox for email.
                Delete app/agent/channels/{slack,email}.rb to disable.
-            8. Inbox: live at /silas/inbox once you set config.inbox_auth
-               (deny-by-default until you do).
+            8. Inbox + web chat: /silas/inbox, deny-by-default — uncomment
+               config.inbox_auth in config/initializers/silas.rb to make it visible.
+            9. Restart your server if it was running (app/agent/ registers at boot).
         MSG
       end
     end

data/lib/generators/silas/install/templates/bin_ci

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# CI gate: your app tests, then the agent evals (deterministic; non-zero on failure).
+# CI gate: your app tests, then the agent evals. Either failing fails the gate.
 set -e
 echo "== app tests =="
-bin/rails test 2>/dev/null || true
+bin/rails test
 echo "== agent evals =="
 bin/rails silas:eval

data/lib/generators/silas/install/templates/initializer.rb

@@ -1,12 +1,20 @@
 Silas.configure do |config|
   # Inference engine: :ruby_llm (API key, any provider RubyLLM supports), or
-  # :agent_sdk (a `claude -p` subprocess; API-key auth only). See silas/README.
+  # any object responding to #execute_step. See silas/README.
   config.engine = :ruby_llm
 
-  # Any model your installed ruby_llm's registry resolves (newer Claude models
-  # may need `RubyLLM.models.refresh!` first). Alternatives: "claude-sonnet-5"
-  # (balanced), "claude-haiku-4-5" (fastest/cheapest).
-  config.default_model = "claude-opus-4-8"
+  # Any model your installed ruby_llm's registry resolves (newer models may
+  # need `RubyLLM.models.refresh!` first). "claude-sonnet-5" is the balanced
+  # default; "claude-haiku-4-5" is fastest/cheapest; Opus models are the most
+  # capable and the most expensive — set per-turn budgets in agent.yml before
+  # reaching for one.
+  config.default_model = "claude-sonnet-5"
+
+  # The operator inbox (mounted at /silas/inbox) is DENY-BY-DEFAULT — invisible
+  # until you wire auth. The lambda DENIES by rendering (or head-ing) and
+  # PASSES by not rendering. Devise-style example:
+  # config.inbox_auth = ->(controller) { controller.head :not_found unless controller.current_user&.admin? }
+  # config.inbox_public_read = true   # read-only demo mode; writes stay gated
 
   # Parked approvals expire after this long (the turn fails as approval_expired).
   # config.approval_ttl = 7.days
@@ -16,4 +24,20 @@ Silas.configure do |config|
 
   # Wrap every model call — e.g. ruby_llm-resilience:
   # config.around_model_call = ->(ctx, &call) { RubyLLM::Resilience.chain(:anthropic) { call.() } }
+
+  # Sandbox for the run_code tool: :none (default, code exec off), :docker, or
+  # a hermetic backend (gem "hermetic"), e.g. Hermetic.gvisor(image: "python:3.12-slim").
+  # config.sandbox = :none
+
+  # Memory (the remember/recall tools): on by default, and every remember
+  # PARKS for human approval. :never auto-approves; config.memory = false
+  # disables memory entirely.
+  # config.memory_approval = :always
+
+  # Cost accounting price overrides: cost-units per 1k tokens, where
+  # 1_000_000 units = $1 (so a $3/M-token rate is 3000).
+  # config.model_prices["your-fine-tune"] = { in: 3000, out: 15_000 }
+
+  # Where eval scenarios live (bin/rails silas:eval).
+  # config.eval_dir = "test/agent_evals"
 end

data/lib/generators/silas/install/templates/ruby_llm.rb

@@ -6,4 +6,8 @@
 # Any provider RubyLLM supports works the same way (openai_api_key, etc.).
 RubyLLM.configure do |c|
   c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  # The per-request timeout (seconds; RubyLLM default 300). Under streaming
+  # this is an idle-between-chunks timeout — the hang protection for a stuck
+  # provider connection.
+  # c.request_timeout = 120
 end if ENV["ANTHROPIC_API_KEY"].present?

data/lib/silas/chat.rb

@@ -22,21 +22,23 @@ module Silas
 
     def run
       banner
-      if @session && pending_for(@session).exists? # resuming a session that parked last time
-        settle_parked
-        print_outcome(@session.turns.reload.last)
-      end
+      with_delta_stream do
+        if @session && pending_for(@session).exists? # resuming a session that parked last time
+          settle_parked
+          print_outcome(@session.turns.reload.last)
+        end
 
-      loop do
-        @out.print "\nyou> "
-        line = @in.gets
-        break if line.nil?
+        loop do
+          @out.print "\nyou> "
+          line = @in.gets
+          break if line.nil?
 
-        line = line.strip
-        next if line.empty?
-        break if %w[exit quit].include?(line.downcase)
+          line = line.strip
+          next if line.empty?
+          break if %w[exit quit].include?(line.downcase)
 
-        submit(line)
+          submit(line)
+        end
       end
       @out.puts "bye — session #{@session.id}" if @session
     end
@@ -56,7 +58,33 @@ module Silas
       @out.puts "Resuming session #{@session.id} (#{@session.turns.count} turns)." if @session
     end
 
+    # The REPL runs inline, in the same process as the loop — so it hears the
+    # "silas.delta" notifications and prints tokens as they arrive. Filtered by
+    # session id: notifications are process-global.
+    def with_delta_stream
+      @live = {}
+      subscription = ActiveSupport::Notifications.subscribe("silas.delta") do |*args|
+        payload = args.last
+        print_delta(payload) if @session && payload[:session_id] == @session.id
+      end
+      yield
+    ensure
+      ActiveSupport::Notifications.unsubscribe(subscription) if subscription
+    end
+
+    def print_delta(payload)
+      printed = @live[payload[:step_id]] || 0
+      text = payload[:text].to_s
+      @out.print "\nagent> " if printed.zero?
+      @out.print text[printed..]
+      @out.flush if @out.respond_to?(:flush)
+      @live[payload[:step_id]] = text.length
+      @last_streamed = text
+    end
+
     def submit(text)
+      @live = {}
+      @last_streamed = nil
       turn =
         if @session.nil?
           @session = agent_handle.start(input: text)
@@ -90,7 +118,11 @@ module Silas
       turn.reload
       case turn.status
       when "completed"
-        @out.puts "agent> #{turn.answer_text}"
+        if @last_streamed.present? && @last_streamed == turn.answer_text
+          @out.puts # the streamed line IS the answer; just terminate it
+        else
+          @out.puts "agent> #{turn.answer_text}"
+        end
       when "waiting", "in_doubt"
         if turn.budget_parked?
           @out.puts "(parked: #{turn.failure_reason} budget reached — resume with " \

data/lib/silas/configuration.rb

@@ -1,9 +1,7 @@
 module Silas
   class Configuration
-    # Inference engine seam: :ruby_llm (Phase 1) or :agent_sdk (stub).
+    # Inference engine seam: :ruby_llm, or any object responding to #execute_step.
     attr_accessor :engine
-    # Auth mode for :agent_sdk — :api_key or :oauth (subscription).
-    attr_accessor :auth
     # Default model when agent.yml doesn't specify one.
     attr_accessor :default_model
     # Active Job queue for agent turns.
@@ -37,9 +35,31 @@ module Silas
     # default to credentials.dig(:silas, :slack, ...); nil disables Slack.
     attr_accessor :channel_resolver
     attr_writer :slack_signing_secret, :slack_bot_token
-    # :agent_sdk engine knobs.
-    attr_accessor :agent_sdk_claude_bin, :agent_sdk_model, :agent_sdk_mcp_host,
-                  :agent_sdk_mcp_timeout_ms, :agent_sdk_cli_version_range
+    # Bind host for the in-process MCP server (Mcp::Server — the "mount your
+    # tools as MCP" seam).
+    attr_accessor :mcp_server_host
+
+    # Removed in 0.2 with the :agent_sdk engine. Accepted as warning no-ops for
+    # one release so an existing initializer doesn't crash at boot; hard removal
+    # in 0.3.
+    REMOVED_AGENT_SDK_OPTIONS = %i[
+      auth agent_sdk_claude_bin agent_sdk_model agent_sdk_mcp_host
+      agent_sdk_mcp_timeout_ms agent_sdk_cli_version_range
+    ].freeze
+
+    REMOVED_AGENT_SDK_OPTIONS.each do |option|
+      define_method("#{option}=") { |_value| warn_removed_agent_sdk_option(option) }
+      define_method(option) do
+        warn_removed_agent_sdk_option(option)
+        nil
+      end
+    end
+
+    def warn_removed_agent_sdk_option(option)
+      message = "[Silas] config.#{option} was removed in 0.2 with the :agent_sdk engine and " \
+                "is now a no-op — delete it from your initializer (hard removal in 0.3)."
+      (defined?(::Rails) && ::Rails.logger ? ::Rails.logger.warn(message) : nil) || Kernel.warn(message)
+    end
     # Inbox (mountable UI at /silas/inbox).
     #   inbox_auth        — deny-by-default lambda; the host renders/head-404s to
     #                       DENY and passes by NOT rendering (resilience pattern).
@@ -70,7 +90,6 @@ module Silas
 
     def initialize
       @engine = :ruby_llm
-      @auth = :api_key
       # Must be resolvable by the installed ruby_llm's model registry — newer
       # Claude models may need `RubyLLM.models.refresh!` before they resolve.
       @default_model = "claude-opus-4-8"
@@ -91,11 +110,7 @@ module Silas
       @channel_resolver = nil
       @slack_signing_secret = nil
       @slack_bot_token = nil
-      @agent_sdk_claude_bin = "claude"
-      @agent_sdk_model = nil # falls back to the agent model; must be a CLI-accepted id
-      @agent_sdk_mcp_host = "127.0.0.1"
-      @agent_sdk_mcp_timeout_ms = 15_000
-      @agent_sdk_cli_version_range = ">= 2.1.150, < 3"
+      @mcp_server_host = "127.0.0.1"
       @eval_dir = "test/agent_evals"
       @eval_grader = nil
       @sandbox = :none
@@ -129,24 +144,45 @@ module Silas
       self
     end
 
-    # PLAN.md §1, non-negotiable: raise if subscription OAuth is configured
-    # while an API key is present — the key would silently win and bill credits.
-    # The inverse also holds: :agent_sdk runs --bare (API-key auth only), so
-    # api_key mode needs a key present.
+    # Fail-loud misconfiguration checks, run from Silas.configure and at boot.
     def boot_guard!
-      if engine == :agent_sdk && auth == :oauth && ENV["ANTHROPIC_API_KEY"].present?
+      if engine == :agent_sdk
         raise BootGuardError,
-              "engine :agent_sdk with auth: :oauth is configured, but ANTHROPIC_API_KEY exists " \
-              "in the environment. The key would silently override subscription OAuth and drain " \
-              "API credits. Unset ANTHROPIC_API_KEY or switch to auth: :api_key."
+              "the :agent_sdk engine was removed in Silas 0.2 — the claude -p subprocess " \
+              "integration is gone (its subscription-auth rationale was unreachable). " \
+              "Use engine :ruby_llm, the production path."
       end
 
-      if engine == :agent_sdk && auth == :api_key && ENV["ANTHROPIC_API_KEY"].blank?
-        raise BootGuardError,
-              "engine :agent_sdk uses --bare (API-key auth only) but ANTHROPIC_API_KEY is not set."
+      check_provider_credentials!
+      warn_unsafe_queue_adapter!
+    end
+
+    # The most common first-run failure: no provider key configured, so the
+    # first turn dies deep inside RubyLLM with a third-party error. Surface it
+    # at boot with the fix. Raises in production (a keyless prod deploy is
+    # always a misconfiguration); warns in development so a fresh app can
+    # still boot and browse the inbox before a key exists.
+    def check_provider_credentials!
+      return unless engine == :ruby_llm && defined?(::RubyLLM)
+
+      providers = ::RubyLLM::Provider.providers.values
+      configured = providers.any? do |provider|
+        requirements = provider.configuration_requirements
+        requirements.any? && requirements.all? { |key| ::RubyLLM.config.public_send(key).present? }
       end
+      return if configured
 
-      warn_unsafe_queue_adapter!
+      message = "[Silas] engine :ruby_llm has no configured provider — no API key is set on " \
+                "RubyLLM.config. Set one in config/initializers/ruby_llm.rb, e.g. " \
+                "RubyLLM.configure { |c| c.anthropic_api_key = ENV[\"ANTHROPIC_API_KEY\"] } " \
+                "— the first agent turn will fail without it."
+      raise BootGuardError, message if defined?(::Rails) && ::Rails.env.production?
+
+      (defined?(::Rails) && ::Rails.logger ? ::Rails.logger.warn(message) : nil) || Kernel.warn(message)
+    rescue BootGuardError
+      raise
+    rescue StandardError
+      nil # a diagnostic must never break boot
     end
 
     # Silas's durability and exactly-once guarantees rest on the queue adapter:
@@ -158,6 +194,10 @@ module Silas
     # mints new tool_call ids the ledger cannot dedup). Solid Queue — or any
     # durable, serializing, DB-backed adapter — is required to run agents; the
     # synchronous :inline adapter is safe for scripts and demos (no durability).
+    #
+    # RAISES in production — running agents on the Async adapter there silently
+    # voids the durability contract. Warns in development (Rails' dev default
+    # is :async and a fresh app must still boot).
     def warn_unsafe_queue_adapter!
       return unless defined?(::ActiveJob::Base)
 
@@ -169,7 +209,11 @@ module Silas
                 "the original job, which double-executes agent steps and breaks " \
                 "exactly-once tool effects. Use :solid_queue (production) or " \
                 ":inline (scripts/demos). See Silas DEPLOY.md."
+      raise BootGuardError, message if defined?(::Rails) && ::Rails.env.production?
+
       (defined?(::Rails) && ::Rails.logger ? ::Rails.logger.warn(message) : nil) || Kernel.warn(message)
+    rescue BootGuardError
+      raise
     rescue StandardError
       # A diagnostic must never break boot.
       nil

data/lib/silas/delta_buffer.rb

@@ -0,0 +1,50 @@
+module Silas
+  # Coalesces model text deltas into ~10Hz "silas.delta" notifications carrying
+  # the ACCUMULATED text so far — subscribers replace rather than append, which
+  # is idempotent under a crash-restream (same step id, fresh stream overwrites
+  # itself) and ordering-safe under Turbo. Deltas are decoration over the
+  # authoritative row render: never persisted, never fed back to the model, and
+  # a replayed step (already completed) emits none.
+  #
+  # Payload: { session_id:, turn_id:, step_id:, step_index:, text: } — every
+  # subscriber MUST filter by these ids (notifications are process-global; a
+  # busy worker interleaves deltas from concurrent turns).
+  class DeltaBuffer
+    INTERVAL = 0.1 # seconds between publishes; #finish flushes the tail
+
+    def initialize(turn:, step:)
+      @turn = turn
+      @step = step
+      @text = +""
+      @published = 0
+      @last_publish = 0.0
+    end
+
+    def append(text)
+      return if text.empty?
+
+      @text << text
+      publish if clock - @last_publish >= INTERVAL
+    end
+
+    # The final flush. StepRunner calls this BEFORE the step row commits, so
+    # the authoritative after_commit render can never race a straggling batch.
+    def finish = publish
+
+    private
+
+    def publish
+      return if @text.empty? || @text.length == @published
+
+      @published = @text.length
+      @last_publish = clock
+      ActiveSupport::Notifications.instrument(
+        "silas.delta",
+        session_id: @turn.session_id, turn_id: @turn.id,
+        step_id: @step.id, step_index: @step.index, text: @text.dup
+      )
+    end
+
+    def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/silas/engine.rb

@@ -37,6 +37,12 @@ module Silas
       Silas.config.boot_guard!
     end
 
+    # Live token streaming into the inbox trace: one process-wide subscriber on
+    # "silas.delta"; a no-op unless turbo-rails is present and streaming is on.
+    initializer "silas.delta_broadcaster" do
+      Silas::Inbox::DeltaBroadcaster.subscribe!
+    end
+
     # Registry rebuilds on every code reload in development, once in production.
     initializer "silas.registry" do |app|
       next unless app.root.join("app/agent").exist? || app.root.join("app/agents").exist?

data/lib/silas/engines/base.rb

@@ -1,8 +1,10 @@
 module Silas
-  # Streamed event from an engine (or the framework) during a step.
-  # Types: :text_delta, :tool_call, :thinking, :usage — and :approval_request,
-  # which only :engine-owned loops (agent_sdk) emit; in :framework-owned loops
-  # approvals are a Ledger concern, never an engine event.
+  # Streamed event from an engine during a step. The type vocabulary is an open
+  # set — consumers must ignore unknown types. Emitted today by Engines::RubyLLM:
+  #   :message_start — once per model call (before_message)
+  #   :text_delta    — { text: } chunks as the response streams
+  # StepRunner coalesces :text_delta into "silas.delta" notifications (see
+  # DeltaBuffer); everything else is available to custom engines/hooks.
   Event = Data.define(:type, :payload)
 
   module Engines
@@ -10,10 +12,6 @@ module Silas
     # and reports what came back; the framework owns the loop, the ledger owns
     # tool execution.
     class Base
-      # :framework — Silas's AgentLoopJob drives the loop (ruby_llm).
-      # :engine    — the engine drives its own loop (agent_sdk, future).
-      def self.loop_ownership = :framework
-
       # context: { turn:, index:, system:, messages:, tools:, model:, limits: }
       # Yields Silas::Event objects as they stream; returns a Result.
       def execute_step(context, &on_event)

data/lib/silas/engines/ruby_llm.rb

@@ -8,8 +8,6 @@ module Silas
     class RubyLLM < Base
       INTERCEPTED = "__silas_intercepted__".freeze
 
-      def self.loop_ownership = :framework
-
       def execute_step(context, &on_event)
         chat = build_chat(context, &on_event)
 
@@ -17,7 +15,17 @@ module Silas
                                                            turn_id: context[:turn]&.id,
                                                            index: context[:index],
                                                            model: context[:model]) do
-          chat.complete
+          if on_event
+            # Streamed: RubyLLM's accumulator returns a Message identical in
+            # shape to the sync path, so to_result needs no branch. Chunks with
+            # tool-call fragments carry nil/empty content — only text streams.
+            chat.complete do |chunk|
+              text = chunk.content
+              on_event.call(Event.new(type: :text_delta, payload: { text: text })) if text.is_a?(String) && !text.empty?
+            end
+          else
+            chat.complete
+          end
         end
 
         to_result(chat, response)
@@ -40,7 +48,10 @@ module Silas
         replay_history(chat, context[:messages])
 
         if on_event
-          chat.on_new_message { on_event.call(Event.new(type: :message_start, payload: {})) }
+          # before_message replaces the deprecated on_new_message (gone in
+          # RubyLLM 2.0). Under streaming it fires BEFORE the HTTP request —
+          # deliberate; don't "fix" the earlier timing.
+          chat.before_message { on_event.call(Event.new(type: :message_start, payload: {})) }
         end
         chat
       end

data/lib/silas/errors.rb

@@ -1,9 +1,9 @@
 module Silas
   class Error < StandardError; end
 
-  # The :agent_sdk + OAuth footgun (PLAN.md boot guard, non-negotiable): an
-  # ANTHROPIC_API_KEY in the environment would silently override subscription
-  # OAuth and drain credits.
+  # A fatal misconfiguration detected at boot — e.g. a removed engine still
+  # configured, or a missing API key for the configured engine. Fail loud at
+  # configure time, never on the first turn.
   class BootGuardError < Error; end
 
   # A continuation checkpoint occurred inside a ledger transaction. Checkpoints

data/lib/silas/eval/scripted_engine.rb

@@ -4,8 +4,6 @@ module Silas
     # eval script the MODEL's decisions while the REAL Ledger runs the REAL tools —
     # so assertions see a genuine transcript.
     class ScriptedEngine < Silas::Engines::Base
-      def self.loop_ownership = :framework
-
       attr_reader :calls
 
       def initialize(steps)

data/lib/silas/inbox/delta_broadcaster.rb

@@ -0,0 +1,38 @@
+module Silas
+  module Inbox
+    # Streams accumulated step text into the live trace as it arrives.
+    #
+    # Synchronous on purpose: broadcast_update_to, not _later — the row
+    # broadcasts ride ActiveJob because they are rare; a delta batch every
+    # ~100ms per running turn would swamp the queue. The push happens on the
+    # worker thread mid-model-call, so it is wrapped: a cable/render failure
+    # can NEVER re-raise into the durable loop.
+    #
+    # Deltas are decoration. The authoritative after_commit row render replaces
+    # the whole step partial (dom_id target) and supersedes anything streamed
+    # into the inner text container.
+    module DeltaBroadcaster
+      EVENT = "silas.delta".freeze
+
+      class << self
+        def subscribe!
+          @subscription ||= ActiveSupport::Notifications.subscribe(EVENT) do |*args|
+            broadcast(args.last)
+          end
+        end
+
+        def broadcast(payload)
+          return unless Silas::Inbox.streaming?
+
+          Turbo::StreamsChannel.broadcast_update_to(
+            Silas::Inbox.stream_name(payload[:session_id]),
+            target: "silas-step-#{payload[:step_id]}-text",
+            html: ERB::Util.html_escape(payload[:text]) # plain text; the row render owns formatting
+          )
+        rescue StandardError => e
+          Rails.logger&.warn("[silas.inbox] delta broadcast failed: #{e.class}: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/silas/ledger.rb

@@ -20,10 +20,16 @@ module Silas
     GUARD_KEY = :silas_ledger_transaction
 
     class << self
-      # True while a ledger transaction is open on this thread. A continuation
-      # checkpoint inside would raise Interrupt and roll back committed-looking
-      # progress (spike finding #5) — AgentLoopJob asserts against this.
-      def in_transaction? = Thread.current[GUARD_KEY] == true
+      # True while a ledger transaction is open in this execution context. A
+      # continuation checkpoint inside would raise Interrupt and roll back
+      # committed-looking progress (spike finding #5) — AgentLoopJob asserts
+      # against this. Stored in IsolatedExecutionState (not Thread.current[],
+      # which is fiber-local) so the guard follows the app's configured
+      # isolation level, exactly like Silas.current_scope — under the default
+      # :thread isolation it survives into internally-created fibers
+      # (enumerators, streaming bodies) where a fiber-local flag would
+      # silently vanish.
+      def in_transaction? = ActiveSupport::IsolatedExecutionState[GUARD_KEY] == true
 
       def assert_no_checkpoint!
         return unless in_transaction?
@@ -50,9 +56,9 @@ module Silas
       end
 
       # Drive a SINGLE freshly-created invocation to a terminal state — the
-      # :agent_sdk MCP endpoint creates one invocation per tools/call and needs
-      # exactly the same exactly-once/effect-mode machinery as settle!. Returns
-      # :done or :parked; the invocation carries its .result.
+      # hosted MCP endpoint (Mcp::Handler) creates one invocation per tools/call
+      # and needs exactly the same exactly-once/effect-mode machinery as
+      # settle!. Returns :done or :parked; the invocation carries its .result.
       def execute_invocation!(invocation, resolver:)
         settle_invocation!(invocation, resolver)
       end
@@ -157,12 +163,18 @@ module Silas
         end
       end
 
+      # :once is scoped to tool name AND arguments. Name-only matching was a
+      # footgun: approving a £5 refund would silently auto-approve a £5,000
+      # refund later in the same session. Identical repeat calls still skip
+      # re-approval; anything else re-parks. Graded gates (thresholds, ranges)
+      # belong in an approval lambda, not :once. (Hash#== is order-independent,
+      # so jsonb key order can't produce false negatives.)
       def previously_approved?(invocation)
         ToolInvocation.joins(:turn)
                       .where(silas_turns: { session_id: invocation.turn.session_id },
                              tool_name: invocation.tool_name, approval_state: "approved")
                       .where.not(id: invocation.id)
-                      .exists?
+                      .any? { |prior| prior.arguments == invocation.arguments }
       end
 
       # Compare-and-swap claim: only one racing execution wins.
@@ -173,11 +185,15 @@ module Silas
         claimed
       end
 
+      # Save/restore, not set/clear: a nested guarded_transaction must not
+      # clobber the outer guard on exit (the old `ensure ... = false` opened a
+      # checkpoint-guard hole for the remainder of the outer transaction).
       def guarded_transaction
-        Thread.current[GUARD_KEY] = true
+        previous = ActiveSupport::IsolatedExecutionState[GUARD_KEY]
+        ActiveSupport::IsolatedExecutionState[GUARD_KEY] = true
         ApplicationRecord.transaction { yield }
       ensure
-        Thread.current[GUARD_KEY] = false
+        ActiveSupport::IsolatedExecutionState[GUARD_KEY] = previous
       end
 
       def wrap_result(result)

data/lib/silas/mcp/handler.rb

@@ -4,9 +4,9 @@ require "securerandom"
 module Silas
   module Mcp
     # JSON-RPC handler for the hosted MCP endpoint. tools/call runs the tool
-    # THROUGH the Ledger, so the :agent_sdk path gets the same exactly-once and
-    # effect-mode semantics as :ruby_llm. Closes over one turn + its anchor step;
-    # authenticated by a per-turn bearer token in the URL query.
+    # THROUGH the Ledger, so a remote MCP caller gets the same exactly-once and
+    # effect-mode semantics as the in-process loop. Closes over one turn + its
+    # anchor step; authenticated by a bearer token in the URL query.
     class Handler
       TOOL_PREFIX = "mcp__silas__".freeze
 
@@ -50,8 +50,9 @@ module Silas
         invocation.reload
 
         if outcome == :parked
-          # v1 excludes approval-gated tools; if one slips through, fail loud.
-          { "isError" => true, "content" => [ text_content("approval-gated tools are not supported by :agent_sdk") ] }
+          # The hosted endpoint excludes approval-gated tools; if one slips
+          # through, fail loud rather than park a caller that can't wait.
+          { "isError" => true, "content" => [ text_content("approval-gated tools are not supported over the hosted MCP endpoint") ] }
         else
           { "content" => [ text_content(JSON.generate(invocation.result)) ] }
         end