nexo_ai 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8815820e94035d1d5c68defa4e862111c95572852098b735e885eaf98b6a3407
-  data.tar.gz: 57ca3d98c0d1acd6877276e9322715a7e003928b2da258866b1e7ccabcf33b29
+  metadata.gz: 2a372c4ac5c253a76cbf930d99b134bbdc62c596dc8bde4414da26f08c99ad39
+  data.tar.gz: 8329003fd163b8b4131f4608b18ecb5604717b7dd6995699328216cb22143320
 SHA512:
-  metadata.gz: 8ad1a55220bcddd2ea1e2d06ea2bc2c680ae4f2a52c1cd8f24e0942f66ad38e38c6b1dc992fcc766b720400083bb07b500feaae9285fbb671e203bfa3f46e0f4
-  data.tar.gz: cea3ce8167dae3b4e44a5d87c84e42f04a333c7cd7e5aae8ad236133b821ba10fd3688e63851035d2c1b494b9c533807fa29bfbfd1c3439ed8c8ce6473fe1e52
+  metadata.gz: 3e3de8747793d6c7b052d9272f6e23345e33d0749e66cd17a4247429eec1999f1329830c1c21841ac399bc04743f2d6595126496d8a24d340b537ad5ee4de026
+  data.tar.gz: 271699e28b6c236f618250b06f75ed8c4fc5d0dec269d24d0f4bac145366e1cedc0f6fee37926117b9fbf2446a8d4d7b54054f2c73562f3d6a1bfd6ae41e21d5

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-20
+
+An agent's tool schema now tells the truth about what it may do.
+
+### Changed
+
+- **An agent no longer advertises a tool its permission mode can never authorize.**
+  Tool attach was gated on the sandbox (`Sandbox#supports?`) but not on the gate, so a
+  `:read_only` agent — the default — put `WriteFile` and `Shell` in its schema on every
+  turn even though `#authorize!` was guaranteed to deny them. The same held for `Fetch`
+  and `WebSearch`, which were gated on `fetch_allow` / `search_backend` being declared
+  but not on the capability being permitted. Models do try these tools, and each attempt
+  costs a full round trip.
+
+  `Agent#chat`, `#apply_fetch` and `#apply_search` now also consult
+  `Permissions#never_allows?`. Only `:read_only` is decidable ahead of time; `:auto`,
+  `:ask` and `:approve` decide per call and still attach — `:approve` in particular must
+  reach the gate so it can raise `ApprovalRequired` and suspend the run.
+
+  This is a cost and description-accuracy measure, **not** a security change:
+  `#authorize!` remains the boundary and still denies at call time.
+
+  **Upgrading:** an agent that is supposed to write, shell out, fetch or search needs the
+  capability in `allow:` (or a non-`:read_only` mode). If it does not have it today the
+  tool was already failing on every call — the tool now disappears from the schema instead
+  of erroring. Note that `fetch_allow` scopes hosts and `search_backend` names a backend;
+  neither is a capability grant.
+
+### Added
+
+- `Nexo::Permissions#never_allows?(capability)` — true when a capability can never be
+  authorized for this gate, for any call. Derived from the new `Permissions::PRIVILEGED`
+  constant, which `#authorize!` also reads, so the predicate cannot drift from the gate.
+
 ## [0.10.0] - 2026-08-20
 
 Durable workflows without a database.

data/docs/permissions.md

@@ -8,7 +8,7 @@ and the agent loop continues — it does not raise. A path that escapes the work
 
 |                          | `:read` | `:glob` | `:write`            | `:shell`                          | `:fetch`   | `:search`  |
 | ------------------------ | ------- | ------- | ------------------- | --------------------------------- | ---------- | ---------- |
-| `:read_only` (default)   | ✅      | ✅      | ❌ `{error}`        | ❌ `{error}`                      | ❌ `{error}` | ❌ `{error}` |
+| `:read_only` (default)   | ✅      | ✅      | ❌ not attached ‡   | ❌ not attached ‡                 | ❌ not attached ‡ | ❌ not attached ‡ |
 | `:auto`                  | ✅      | ✅      | ✅                  | ✅                                | ✅         | ✅         |
 | `:ask`                   | ✅      | ✅      | per `on_ask`        | per `on_ask`                      | per `on_ask` | per `on_ask` |
 | `:approve`               | ✅      | ✅      | per `decision`      | per `decision`                    | per `decision` | per `decision` |
@@ -18,7 +18,22 @@ and the agent loop continues — it does not raise. A path that escapes the work
 
 `:read`/`:glob` are auto-allowed under **every** mode (they sit in the default
 `allow` list), so `:ask`/`:approve` never prompt for them — only
-`:write`/`:shell`/`:fetch`/`:search` reach the gate. **†** `:fetch` and `:search`
+`:write`/`:shell`/`:fetch`/`:search` reach the gate.
+
+**‡** Under `:read_only` these four capabilities can *never* be authorized, so their tools are
+not attached at all — the model never sees `WriteFile`, `Shell`, `Fetch` or `WebSearch` in its
+schema. Anything named in `allow:` is exempt and attaches normally, and `:auto`/`:ask`/`:approve`
+always attach because they decide per call. Leaving a guaranteed failure in the schema is not
+free: a model that reads the schema tries the tool, and each attempt costs a full round trip.
+`Permissions#never_allows?` is the predicate, and it is derived from the same `PRIVILEGED` list
+`#authorize!` uses so the two cannot disagree. This is a cost and description-accuracy measure,
+**not** a security boundary — `#authorize!` is still the gate and still denies at call time.
+
+Note that declaring `fetch_allow` or a `search_backend` is *not* a capability grant: `fetch_allow`
+scopes which hosts are reachable, and both still need `:fetch` / `:search` permitted before the
+tool is attached.
+
+**†** `:fetch` and `:search`
 run in the **host process** (stdlib `net/http` / a host-injected backend), so **no
 sandbox constrains them** — not even a `--network none` container. They are bounded
 only by the capability gate above plus `fetch_allow` / the injected backend.

data/docs/sandboxes.md

@@ -54,10 +54,19 @@ scope; none widens authority silently.
   instructions → sandbox instructions → skill instructions**. Provider-neutral, injected through
   the existing `with_instructions` path.
 
-- **Capability-gated tool attach (`Sandbox#supports?`).** A `:virtual` agent no longer advertises
-  a `Shell` tool it can never run — `Agent#chat` attaches `Shell` only when
-  `@sandbox.supports?(:shell)`. `Local`/`Container` support all four capabilities; `Virtual`
-  supports everything but `:shell`. `ReadFile`/`WriteFile`/`Glob` are always attached.
+- **Gated tool attach, on two axes.** An agent does not advertise a tool it could never
+  successfully call, because a guaranteed failure in the schema costs a round trip every time a
+  model tries it. `Agent#chat` attaches a tool only when **both** hold:
+
+  1. *The sandbox supports the capability* (`Sandbox#supports?`). `Local`/`Container` support all
+     four; `Virtual` supports everything but `:shell`, so a `:virtual` agent has no `Shell`.
+  2. *The permission gate does not deny it statically* (`Permissions#never_allows?`). Under
+     `:read_only`, `:write` and `:shell` can never be authorized unless listed in `allow:`, so
+     neither `WriteFile` nor `Shell` is attached. `:auto`, `:ask` and `:approve` decide per call
+     and always attach — `:approve` in particular *must* reach the gate so it can suspend the run.
+
+  `ReadFile` and `Glob` are always attached. This is a cost and description-accuracy measure, not
+  a security boundary: `Permissions#authorize!` remains the gate and still denies at call time.
 
 - **Shell output truncation (`Nexo::OutputTruncator`).** Unbounded command output (`npm install`,
   `git log`) is truncated before it reaches the model, so a single command can't blow a small

data/docs/tools.md

@@ -1,12 +1,22 @@
 # Tools
 Nexo attaches four sandbox-backed tools — `ReadFile`, `WriteFile`, `Shell`, and `Glob` — each gated by the [sandbox](sandboxes.md) and [permission](permissions.md) seams.
 
-Which tools attach depends on what the sandbox supports:
-
-- **Capability-gated tool attach (`Sandbox#supports?`).** A `:virtual` agent no longer advertises
-  a `Shell` tool it can never run — `Agent#chat` attaches `Shell` only when
-  `@sandbox.supports?(:shell)`. `Local`/`Container` support all four capabilities; `Virtual`
-  supports everything but `:shell`. `ReadFile`/`WriteFile`/`Glob` are always attached.
+Which tools attach depends on what the sandbox supports *and* on what the permission mode could
+ever allow:
+
+- **Gated tool attach, on two axes.** An agent does not advertise a tool it could never
+  successfully call, because a guaranteed failure in the schema costs a round trip every time a
+  model tries it. `Agent#chat` attaches a tool only when **both** hold:
+
+  1. *The sandbox supports the capability* (`Sandbox#supports?`). `Local`/`Container` support all
+     four; `Virtual` supports everything but `:shell`, so a `:virtual` agent has no `Shell`.
+  2. *The permission gate does not deny it statically* (`Permissions#never_allows?`). Under
+     `:read_only`, `:write` and `:shell` can never be authorized unless listed in `allow:`, so
+     neither `WriteFile` nor `Shell` is attached. `:auto`, `:ask` and `:approve` decide per call
+     and always attach — `:approve` in particular *must* reach the gate so it can suspend the run.
+
+  `ReadFile` and `Glob` are always attached. This is a cost and description-accuracy measure, not
+  a security boundary: `Permissions#authorize!` remains the gate and still denies at call time.
 
 `Shell` truncates unbounded command output before it reaches the model:
 

data/lib/nexo/agent.rb

@@ -285,14 +285,19 @@ module Nexo
       # One ReadTracker per chat, shared by ReadFile (records) and WriteFile
       # (enforces the read-before-write + stale guard) — R4.
       tracker = ReadTracker.new
-      tools = [
-        Tools::ReadFile.new(sandbox: @sandbox, permissions: @permissions, tracker: tracker),
-        Tools::WriteFile.new(sandbox: @sandbox, permissions: @permissions, tracker: tracker),
-        Tools::Glob.new(sandbox: @sandbox, permissions: @permissions)
-      ]
-      # Attach Shell only when the sandbox can actually run one (R2), so a
-      # :virtual agent stops advertising a tool it can never run.
-      if @sandbox.supports?(:shell)
+      # A sandbox tool is attached only when the agent could actually use it, on
+      # BOTH axes: the sandbox has to support the capability (R2 — a :virtual
+      # sandbox has no shell) and the gate must not deny it statically (a
+      # :read_only agent can never be authorized for :write or :shell). Otherwise
+      # a guaranteed failure sits in the tool schema on every turn and models do
+      # try it. This is the same attach-time gating apply_fetch/apply_search
+      # already apply; #authorize! stays the actual boundary either way.
+      tools = [Tools::ReadFile.new(sandbox: @sandbox, permissions: @permissions, tracker: tracker)]
+      unless @permissions.never_allows?(:write)
+        tools << Tools::WriteFile.new(sandbox: @sandbox, permissions: @permissions, tracker: tracker)
+      end
+      tools << Tools::Glob.new(sandbox: @sandbox, permissions: @permissions)
+      if @sandbox.supports?(:shell) && !@permissions.never_allows?(:shell)
         tools << Tools::Shell.new(sandbox: @sandbox, permissions: @permissions)
       end
       c.with_tools(*tools)
@@ -570,6 +575,10 @@ module Nexo
     # allow-list only scopes hosts, it is not the capability grant.
     def apply_fetch(chat)
       return if self.class.fetch_allow.empty?
+      # The allow-list scopes hosts; it is not the capability grant. A gate that
+      # can never authorize :fetch gets no tool rather than a guaranteed failure
+      # in its schema (see Permissions#never_allows?).
+      return if @permissions.never_allows?(:fetch)
 
       chat.with_tools(
         Tools::Fetch.new(sandbox: @sandbox, permissions: @permissions, allow_hosts: self.class.fetch_allow)
@@ -585,6 +594,7 @@ module Nexo
     # through Permissions#authorize! at call time.
     def apply_search(chat)
       backend = self.class.search_backend or return
+      return if @permissions.never_allows?(:search)
 
       chat.with_tools(
         Tools::WebSearch.new(sandbox: @sandbox, permissions: @permissions, backend: backend)

data/lib/nexo/permissions.rb

@@ -20,6 +20,11 @@ module Nexo
     # The recognized permission modes: +:auto+, +:read_only+, +:ask+, +:approve+.
     MODES = %i[auto read_only ask approve].freeze
 
+    # The capabilities +:read_only+ refuses. Named once so #authorize! and
+    # #never_allows? cannot drift apart: the whole value of the predicate is that
+    # it reports what the gate will actually do, so both must read the same list.
+    PRIVILEGED = %i[write shell fetch search].freeze
+
     # Raised when a capability is not authorized. Tools rescue this and return
     # +{ error: ... }+ so the agent loop continues.
     class Denied < StandardError; end
@@ -76,9 +81,8 @@ module Nexo
       when :auto
         true
       when :read_only
-        if %i[write shell fetch search].include?(capability)
-          raise Denied, "#{capability} denied in read_only mode"
-        end
+        raise Denied, "#{capability} denied in read_only mode" if PRIVILEGED.include?(capability)
+
         true
       when :ask
         # Scoped-ask: when ask_when says this action doesn't need a prompt,
@@ -109,6 +113,25 @@ module Nexo
       end
     end
 
+    # Whether +capability+ can NEVER be authorized by this gate, for any call.
+    #
+    # True only under +:read_only+, for a PRIVILEGED capability absent from
+    # +allow:+ — that is the one case knowable ahead of time. Every other mode
+    # decides per call and must be reported as *possible*: +:auto+ allows, +:ask+
+    # consults its hook, and +:approve+ has to reach the gate so it can raise
+    # ApprovalRequired and suspend the run.
+    #
+    # Agent#chat uses this to skip ATTACHING a tool the model could never
+    # successfully call, so a guaranteed failure stops occupying the tool schema
+    # on every turn. That makes this a cost and description-accuracy measure, not
+    # a security boundary: #authorize! remains the gate and still denies at call
+    # time whether or not the tool was advertised.
+    def never_allows?(capability)
+      return false if @allow.include?(capability)
+
+      @mode == :read_only && PRIVILEGED.include?(capability)
+    end
+
     # Authorizes an MCP tool *call* by name. A deliberate sibling of #authorize!
     # on a separate capability axis: an MCP tool runs inside the MCP server,
     # outside the sandbox, so this gates the authority to *invoke* it — a different

data/lib/nexo/version.rb

@@ -2,5 +2,5 @@
 
 module Nexo
   # The gem version (also used as +spec.version+ in the gemspec).
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexo_ai
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Mario Alberto Chávez