agent_jail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cbe7c9edb7dc3c7d7300b5617162dd80bc63d278d83a42f8afbede50bf2e45f1
+  data.tar.gz: f50d55b8ff825febc26a1c74592f91ca70ca0fcd0ee90753cf44d8aac4461b7d
+SHA512:
+  metadata.gz: 6a2f0343e61d99643735a35d6cba6b871fe9f176bf2168375c88e4d0bc7150da8b07717bafd4873055a2ec60d40520c9072f678c3184ecd71fbdd8a89df76a45
+  data.tar.gz: a9964bff1b0ffc418cda699527b2aa0e7fd7c1e7830314c849a08a9e1dfe355860635aa099ba4e62bba4ac35f3fe2c9df8e27c0ada7909ab33a9a58b8495e7bf

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,107 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  Exclude:
+    - "bin/**/*"
+    - "vendor/**/*"
+    - "pkg/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - "spec/**/*"
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Style/Documentation:
+  Enabled: false
+
+Naming/MethodParameterName:
+  MinNameLength: 1
+
+Naming/PredicateMethod:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/IdenticalEqualityAssertion:
+  Enabled: false
+
+RSpec/StubbedMock:
+  Enabled: false
+
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 12
+
+Metrics/ParameterLists:
+  Max: 8
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 8
+
+RSpec/ExampleLength:
+  Max: 30
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+Lint/EmptyBlock:
+  Exclude:
+    - "spec/**/*"
+
+# Security/MarshalLoad is acknowledged — we only load data we wrote ourselves
+# (child → parent pipe), never from external input.
+Security/MarshalLoad:
+  Enabled: false
+
+# Lint/RescueException is needed in Child#run to catch all exceptions from the block
+# and forward them over the pipe rather than crashing the child process.
+Lint/RescueException:
+  Exclude:
+    - "lib/agent_jail/child.rb"
+
+# set_memory / set_cpu are not property setters; they apply OS-level resource limits.
+Naming/AccessorMethodName:
+  Enabled: false
+
+# Spec files legitimately test multiple related classes in one file.
+RSpec/MultipleDescribes:
+  Enabled: false
+
+# Common RSpec pattern: multiline expect block followed by assertion on the error.
+Style/MultilineBlockChain:
+  Enabled: false
+
+# $test_agent_jail_var is used to assert fork isolation (child doesn't mutate parent globals).
+Style/GlobalVars:
+  Exclude:
+    - "spec/**/*"

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.0] — 2026-06-09
+
+### Added
+- `AgentJail.run` — fork + pipe + monitor pattern for sandboxed block execution
+- Linux Landlock LSM filesystem restrictions (kernel >= 5.13) via FFI syscalls (444/445/446)
+- macOS Seatbelt (`sandbox_init`) filesystem restrictions via FFI
+- POSIX resource limits: address space (`RLIMIT_AS`) and CPU time (`RLIMIT_CPU`) via `setrlimit`
+- Wall-clock timeout enforced by a monitor thread in the parent process
+- Typed exception hierarchy: `TimeoutError`, `MemoryError`, `FilesystemError`, `SandboxError`, `UnsupportedPlatformError`
+- `SandboxError` wraps block exceptions with `original_class`, `original_message`, `original_backtrace`
+- `AgentJail.configure` block with `default_timeout`, `default_memory_mb`, `default_fs_allow`, `on_unsupported`
+- Graceful degradation on unsupported platforms (`:warn`, `:raise`, `:ignore`)
+- `fs_allow` (read-write) and `fs_read_allow` (read-only) per-run path lists
+- Implicit system read-only paths so Ruby functions correctly inside the sandbox

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jibran Usman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,243 @@
+# agent_jail
+
+**Run LLM-generated tool calls in a sandboxed child process — timeout, memory limit, filesystem restrictions.**
+
+[![CI](https://github.com/jibranusman95/agent_jail/actions/workflows/ci.yml/badge.svg)](https://github.com/jibranusman95/agent_jail/actions)
+[![Gem Version](https://badge.fury.io/rb/agent_jail.svg)](https://badge.fury.io/rb/agent_jail)
+[![Downloads](https://img.shields.io/gem/dt/agent_jail)](https://rubygems.org/gems/agent_jail)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+You're building a Rails agent. The LLM generates a tool call. The tool call loops forever, allocates 10GB, or tries to read `/etc/passwd`.
+
+You have no clean way to stop it.
+
+```ruby
+# No protection — this blocks your process indefinitely
+result = tool.call(llm_generated_args)
+
+# Or kills your server
+result = eval(llm_generated_code)
+```
+
+`agent_jail` runs the block in a forked child process with real OS-level restrictions:
+
+```ruby
+result = AgentJail.run(timeout: 5, memory_mb: 256, fs_allow: ["/app/tmp"]) do
+  tool.call(llm_generated_args)
+end
+```
+
+The child is isolated. If it misbehaves, it's killed. The parent gets a typed exception — no crash, no data loss, no runaway process.
+
+---
+
+## What you get
+
+**Timeout enforcement** — wall-clock timeout via a monitor thread in the parent plus CPU time limit via `RLIMIT_CPU`. A sleeping infinite loop is killed just like a CPU-burning one.
+
+**Memory limit** — address space limit via `RLIMIT_AS` (`setrlimit`). The child is killed before it can OOM your server.
+
+**Filesystem restrictions (Linux 5.13+)** — Linux Landlock LSM via direct syscalls (no root, no capabilities needed). Paths outside `fs_allow` are inaccessible at the kernel level, not just at the Ruby level.
+
+**macOS sandbox** — Seatbelt (`sandbox_init`) profile generated from `fs_allow` and applied in the child.
+
+**Typed exceptions** — `TimeoutError`, `MemoryError`, `FilesystemError`, `SandboxError` (wraps block exceptions), `UnsupportedPlatformError`. Catch exactly what you need.
+
+**Block isolation** — uses `fork`, so the block has full access to in-memory state (open connections, loaded gems, closures) without serialization. The child's mutations never affect the parent.
+
+**Graceful degradation** — on Windows or Linux < 5.13, runs the block with resource limits only (or raises, or silently runs unsandboxed — your choice).
+
+---
+
+## Platform support
+
+| Platform | Filesystem isolation | Resource limits | Notes |
+|----------|---------------------|-----------------|-------|
+| Linux >= 5.13 | Landlock LSM | `setrlimit` + wall-clock | Full support |
+| Linux < 5.13 | None (warning logged) | `setrlimit` + wall-clock | Resource limits only |
+| macOS | Seatbelt (`sandbox_init`) | `setrlimit` + wall-clock | Partial — `sandbox_init` is deprecated but functional |
+| Windows | None | None | No-op with warning; set `on_unsupported: :raise` to hard-fail |
+| JRuby / TruffleRuby | None | None | `fork` not available; behaves like Windows |
+
+---
+
+## Install
+
+```ruby
+# Gemfile
+gem "agent_jail"
+```
+
+```
+bundle install
+```
+
+Requires Ruby >= 3.2.
+
+---
+
+## Usage
+
+### Basic — timeout and memory
+
+```ruby
+require "agent_jail"
+
+result = AgentJail.run(timeout: 5, memory_mb: 256) do
+  SomeToolCall.execute(args)
+end
+```
+
+### With filesystem restrictions
+
+```ruby
+result = AgentJail.run(
+  timeout: 10,
+  memory_mb: 512,
+  fs_allow: ["/app/tmp", "/app/uploads"],  # read-write
+  fs_read_allow: ["/app/config"]           # read-only
+) do
+  tool.call(args)
+end
+```
+
+### All options
+
+```ruby
+result = AgentJail.run(
+  timeout:      10,   # wall-clock seconds before child is killed (default: 30)
+  cpu_timeout:  5,    # CPU seconds before child is killed (default: same as timeout)
+  memory_mb:    256,  # address space limit in MB (default: 512)
+  fs_allow:     ["/app/tmp"],    # read-write paths (default: [])
+  fs_read_allow: ["/app/config"] # read-only paths (default: [])
+) do
+  tool.call(args)
+end
+```
+
+### Configuration
+
+```ruby
+AgentJail.configure do |c|
+  c.default_timeout   = 30     # seconds
+  c.default_memory_mb = 512    # MB
+  c.default_fs_allow  = []
+  c.on_unsupported    = :warn  # :warn (default), :raise, or :ignore
+end
+```
+
+`on_unsupported` controls behaviour on platforms where sandboxing is unavailable:
+
+| Value | Behaviour |
+|-------|-----------|
+| `:warn` | Logs a warning to stderr, runs block unsandboxed |
+| `:raise` | Raises `AgentJail::UnsupportedPlatformError` |
+| `:ignore` | Runs block unsandboxed silently |
+
+---
+
+## Exceptions
+
+| Exception | Raised when |
+|-----------|-------------|
+| `AgentJail::TimeoutError` | Block exceeded wall-clock or CPU time limit |
+| `AgentJail::MemoryError` | Block exceeded memory (address space) limit |
+| `AgentJail::FilesystemError` | Block accessed a path outside `fs_allow` (Linux Landlock) |
+| `AgentJail::SandboxError` | Block raised an exception — wraps original with `original_class`, `original_message`, `original_backtrace` |
+| `AgentJail::UnsupportedPlatformError` | Platform can't sandbox and `on_unsupported: :raise` is set |
+
+All inherit from `AgentJail::Error < StandardError`.
+
+```ruby
+begin
+  AgentJail.run(timeout: 5) { tool.call(args) }
+rescue AgentJail::TimeoutError
+  # handle timeout
+rescue AgentJail::MemoryError
+  # handle OOM
+rescue AgentJail::FilesystemError
+  # handle filesystem violation
+rescue AgentJail::SandboxError => e
+  logger.error("Tool call raised #{e.original_class}: #{e.original_message}")
+  logger.error(e.original_backtrace.join("\n"))
+end
+```
+
+---
+
+## How it works
+
+```
+AgentJail.run { block }
+    │
+    ├── opens result_pipe (r, w)
+    ├── fork → Child process
+    │             │
+    │             ├── closes r
+    │             ├── setrlimit (RLIMIT_AS + RLIMIT_CPU)
+    │             ├── Landlock / sandbox_init (if supported)
+    │             ├── runs block
+    │             ├── marshals result → writes to w
+    │             └── exit!(0)
+    │
+    ├── closes w
+    ├── starts monitor thread (wall-clock timeout → SIGKILL)
+    ├── reads result_pipe until EOF
+    ├── Process.waitpid2(child_pid)
+    ├── kills monitor thread
+    └── unmarshals result OR raises TimeoutError/MemoryError
+```
+
+**Why fork?** `fork` copies the full Ruby process including loaded gems, open connections, and closures. The block can reference any in-scope object without serialization. Threads share memory (no isolation); `spawn` requires serializing the block (loses closures, complex). `fork` is the right tool.
+
+**Why both wall-clock and CPU timeout?** `RLIMIT_CPU` limits CPU time — a sleeping process uses no CPU and would never be killed. The monitor thread kills by wall-clock regardless of CPU usage.
+
+**Landlock design:** Landlock ABI v1 syscalls (444/445/446) via FFI. No root or capabilities required — just `prctl(PR_SET_NO_NEW_PRIVS)` first. The child creates a ruleset denying all filesystem access, adds explicit allow rules for system paths (read-only) and user-specified paths, then locks itself in with `landlock_restrict_self`.
+
+---
+
+## Known sharp edges
+
+**Threads + fork:** If your parent process has background threads when `AgentJail.run` is called, the child inherits them in a broken state. Call `AgentJail.run` from a single-threaded context where possible. Background threads in the child are not safe to use.
+
+**Database connections:** `fork` copies open file descriptors including database connections. Do not use ActiveRecord or any connection pool in the block — the child's connections are copies of the parent's and using them will corrupt state. Read-only closures over already-fetched data are fine.
+
+**`RLIMIT_AS` vs RSS:** `RLIMIT_AS` limits virtual address space, not physical RAM. Ruby's VM allocates large virtual ranges upfront. Set `memory_mb` generously (>= 256) to avoid killing the child on startup. The default of 512MB is conservative.
+
+**Return value size:** The result is marshalled over a pipe. Very large return values (> 10MB) will work but are slow. If you need to return large data, write it to an allowed path and return the path.
+
+**MRI only:** `fork` is not available on JRuby or TruffleRuby. `Platform.fork_supported?` returns false on these runtimes and `on_unsupported` kicks in.
+
+---
+
+## Requirements
+
+- Ruby >= 3.2.0
+- Linux kernel >= 5.13 for Landlock filesystem restrictions (kernel detection is automatic)
+- `ffi` gem (the only runtime dependency)
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/jibranusman95/agent_jail.
+
+---
+
+## From the same author
+
+| Gem | What it does |
+|-----|-------------|
+| [http_decoy](https://github.com/jibranusman95/http_decoy) | A real Rack server that runs inside your RSpec tests — test HTTP contracts without WebMock stubs |
+| [llm_cassette](https://github.com/jibranusman95/llm_cassette) | Streaming-aware cassette recorder for LLM calls — record once, replay fast |
+| [webhook_inbox](https://github.com/jibranusman95/webhook_inbox) | Transactional webhook inbox for Rails — deduplicate, replay, inspect |
+| [promptscrub](https://github.com/jibranusman95/promptscrub) | Bidirectional PII redaction middleware for LLM calls |
+| [turbo_presence](https://github.com/jibranusman95/turbo_presence) | Figma-style live cursors and presence in Rails with one line |
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/agent_jail/child.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AgentJail
+  # Runs inside the forked child process.
+  # Applies restrictions then executes the block, writing the result to the pipe.
+  class Child
+    def initialize(write:, cpu_timeout:, memory_mb:, fs_allow:, fs_read_allow:, block:)
+      @write        = write
+      @cpu_timeout  = cpu_timeout
+      @memory_mb    = memory_mb
+      @fs_allow     = fs_allow
+      @fs_read_allow = fs_read_allow
+      @block = block
+    end
+
+    def run
+      apply_restrictions
+
+      begin
+        result = @block.call
+        Pipe.write_result(@write, result)
+      rescue Exception => e
+        Pipe.write_error(@write, e)
+      ensure
+        @write.close
+      end
+    end
+
+    private
+
+    def apply_restrictions
+      # Apply CPU limit first to prevent runaway setup code.
+      # Apply filesystem restrictions before the memory (RLIMIT_AS) limit,
+      # because Landlock setup allocates memory for FFI structs and file descriptors.
+      # Setting RLIMIT_AS too early can cause the setup itself to OOM.
+      AgentJail::FFI::Setrlimit.set_cpu(@cpu_timeout)
+      apply_filesystem_restrictions
+      AgentJail::FFI::Setrlimit.set_memory(@memory_mb * 1024 * 1024)
+    end
+
+    def apply_filesystem_restrictions
+      if Platform.landlock_supported?
+        Restrictions::Landlock.new(
+          fs_allow: @fs_allow,
+          fs_read_allow: @fs_read_allow
+        ).apply
+      elsif Platform.macos?
+        Restrictions::Seatbelt.new(
+          fs_allow: @fs_allow,
+          fs_read_allow: @fs_read_allow
+        ).apply
+      end
+    end
+  end
+end

data/lib/agent_jail/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AgentJail
+  class Configuration
+    VALID_ON_UNSUPPORTED = %i[warn raise ignore].freeze
+
+    attr_accessor :default_timeout, :default_memory_mb, :default_fs_allow, :on_unsupported
+
+    def initialize
+      @default_timeout = 30
+      @default_memory_mb = 512
+      @default_fs_allow = []
+      @on_unsupported = :warn
+    end
+
+    def validate!
+      return if VALID_ON_UNSUPPORTED.include?(@on_unsupported)
+
+      raise ArgumentError,
+            "on_unsupported must be one of #{VALID_ON_UNSUPPORTED.inspect}, got #{@on_unsupported.inspect}"
+    end
+  end
+end

data/lib/agent_jail/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module AgentJail
+  # Base error for all agent_jail exceptions.
+  class Error < StandardError; end
+
+  # Raised when the sandboxed block exceeds the wall-clock or CPU time limit.
+  class TimeoutError < Error; end
+
+  # Raised when the sandboxed block exceeds the memory (address space) limit.
+  class MemoryError < Error; end
+
+  # Raised when the sandboxed block attempts to access a path not in fs_allow.
+  class FilesystemError < Error; end
+
+  # Raised when on_unsupported: :raise and the current platform cannot sandbox.
+  class UnsupportedPlatformError < Error; end
+
+  # Raised when the sandboxed block raises an exception.
+  # Wraps the original exception without requiring the original class to be present.
+  class SandboxError < Error
+    attr_reader :original_class, :original_message, :original_backtrace
+
+    def initialize(original_class:, original_message:, original_backtrace:)
+      @original_class = original_class
+      @original_message = original_message
+      @original_backtrace = original_backtrace
+      super("#{original_class}: #{original_message}")
+    end
+  end
+end

data/lib/agent_jail/ffi/landlock.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module AgentJail
+  module FFI
+    # FFI bindings for the Linux Landlock LSM (kernel 5.13+).
+    # Uses raw syscalls via libc's syscall(2) since Landlock has no libc wrappers.
+    module Landlock
+      extend ::FFI::Library
+
+      ffi_lib ::FFI::Library::LIBC
+
+      # Landlock ABI v1 filesystem access rights
+      ACCESS_FS_EXECUTE    = 1 << 0
+      ACCESS_FS_WRITE_FILE = 1 << 1
+      ACCESS_FS_READ_FILE  = 1 << 2
+      ACCESS_FS_READ_DIR   = 1 << 3
+      ACCESS_FS_REMOVE_DIR = 1 << 4
+      ACCESS_FS_REMOVE_FILE = 1 << 5
+      ACCESS_FS_MAKE_CHAR  = 1 << 6
+      ACCESS_FS_MAKE_DIR   = 1 << 7
+      ACCESS_FS_MAKE_REG   = 1 << 8
+      ACCESS_FS_MAKE_SOCK  = 1 << 9
+      ACCESS_FS_MAKE_FIFO  = 1 << 10
+      ACCESS_FS_MAKE_BLOCK = 1 << 11
+      ACCESS_FS_MAKE_SYM   = 1 << 12
+
+      # Composite access groups
+      ACCESS_FS_READ_WRITE = ACCESS_FS_READ_FILE | ACCESS_FS_READ_DIR |
+                             ACCESS_FS_WRITE_FILE | ACCESS_FS_REMOVE_FILE |
+                             ACCESS_FS_MAKE_REG | ACCESS_FS_MAKE_DIR
+      ACCESS_FS_READ_ONLY  = ACCESS_FS_READ_FILE | ACCESS_FS_READ_DIR
+
+      # All ABI v1 access bits — used in ruleset's handled_access_fs
+      ALL_ACCESS_FS = ACCESS_FS_EXECUTE | ACCESS_FS_WRITE_FILE | ACCESS_FS_READ_FILE |
+                      ACCESS_FS_READ_DIR | ACCESS_FS_REMOVE_DIR | ACCESS_FS_REMOVE_FILE |
+                      ACCESS_FS_MAKE_CHAR | ACCESS_FS_MAKE_DIR | ACCESS_FS_MAKE_REG |
+                      ACCESS_FS_MAKE_SOCK | ACCESS_FS_MAKE_FIFO | ACCESS_FS_MAKE_BLOCK |
+                      ACCESS_FS_MAKE_SYM
+
+      RULE_PATH_BENEATH = 1
+
+      # Syscall numbers (x86_64 Linux)
+      SYS_LANDLOCK_CREATE_RULESET = 444
+      SYS_LANDLOCK_ADD_RULE       = 445
+      SYS_LANDLOCK_RESTRICT_SELF  = 446
+
+      # prctl option
+      PR_SET_NO_NEW_PRIVS = 38
+
+      # struct landlock_ruleset_attr { __u64 handled_access_fs; }
+      class RulesetAttr < ::FFI::Struct
+        layout :handled_access_fs, :uint64
+      end
+
+      # struct landlock_path_beneath_attr — packed (no padding between fields)
+      # __u64 allowed_access; __s32 parent_fd;
+      class PathBeneathAttr < ::FFI::Struct
+        pack 1
+        layout :allowed_access, :uint64,
+               :parent_fd, :int32
+      end
+
+      # syscall(number, ...) — varargs, each extra arg is a (type, value) pair
+      attach_function :syscall, %i[long varargs], :long
+      attach_function :prctl, %i[int ulong ulong ulong ulong], :int
+      attach_function :close, [:int], :int
+
+      def self.create_ruleset(handled_access_fs)
+        attr = RulesetAttr.new
+        attr[:handled_access_fs] = handled_access_fs
+        syscall(SYS_LANDLOCK_CREATE_RULESET, :pointer, attr.to_ptr, :size_t, attr.size, :uint32, 0)
+      end
+
+      def self.add_path_rule(ruleset_fd, path_fd, allowed_access)
+        attr = PathBeneathAttr.new
+        attr[:allowed_access] = allowed_access
+        attr[:parent_fd] = path_fd
+        syscall(SYS_LANDLOCK_ADD_RULE,
+                :int, ruleset_fd,
+                :uint32, RULE_PATH_BENEATH,
+                :pointer, attr.to_ptr,
+                :uint32, 0)
+      end
+
+      def self.restrict_self(ruleset_fd)
+        prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)
+        result = syscall(SYS_LANDLOCK_RESTRICT_SELF, :int, ruleset_fd, :uint32, 0)
+        close(ruleset_fd)
+        result
+      end
+    end
+  end
+end

data/lib/agent_jail/ffi/seatbelt.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module AgentJail
+  module FFI
+    # FFI bindings for macOS Seatbelt (sandbox_init).
+    # sandbox_init(3) is deprecated since macOS 10.8 but remains functional.
+    # No-op stubs are defined when libsandbox is unavailable so the module
+    # always responds to sandbox_init / sandbox_free_error regardless of platform.
+    module Seatbelt
+      extend ::FFI::Library
+
+      AVAILABLE = begin
+        ffi_lib "libsandbox.1.dylib"
+
+        # int sandbox_init(const char *profile, uint64_t flags, char **errorbuf)
+        attach_function :sandbox_init, %i[string uint64 pointer], :int
+        # void sandbox_free_error(char *errorbuf)
+        attach_function :sandbox_free_error, [:pointer], :void
+
+        true
+      rescue LoadError
+        # No-op stubs — callers check AVAILABLE before using; stubs keep the
+        # interface consistent and allow mocking in tests on all platforms.
+        def self.sandbox_init(_profile, _flags, _errbuf)
+          0
+        end
+
+        def self.sandbox_free_error(_errbuf)
+          nil
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/agent_jail/ffi/setrlimit.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module AgentJail
+  module FFI
+    module Setrlimit
+      extend ::FFI::Library
+
+      ffi_lib ::FFI::Library::LIBC
+
+      # rlim_t is uint64 on 64-bit platforms
+      class RLimit < ::FFI::Struct
+        layout :rlim_cur, :uint64,
+               :rlim_max, :uint64
+      end
+
+      # int setrlimit(int resource, const struct rlimit *rlim)
+      attach_function :setrlimit, %i[int pointer], :int
+
+      # POSIX resource limit constants
+      RLIMIT_CPU = 0 # CPU time in seconds
+      # RLIMIT_AS is virtual address space (address space = memory limit)
+      # Linux: 9, macOS: 5
+      RLIMIT_AS_LINUX = 9
+      RLIMIT_AS_MACOS = 5
+
+      def self.rlimit_as
+        RUBY_PLATFORM.include?("darwin") ? RLIMIT_AS_MACOS : RLIMIT_AS_LINUX
+      end
+
+      def self.set_memory(bytes)
+        rlimit = RLimit.new
+        rlimit[:rlim_cur] = bytes
+        rlimit[:rlim_max] = bytes
+        setrlimit(rlimit_as, rlimit)
+      end
+
+      def self.set_cpu(seconds)
+        rlimit = RLimit.new
+        rlimit[:rlim_cur] = seconds
+        rlimit[:rlim_max] = seconds
+        setrlimit(RLIMIT_CPU, rlimit)
+      end
+    end
+  end
+end

data/lib/agent_jail/pipe.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AgentJail
+  # Handles the result pipe protocol between parent and child processes.
+  # The child writes exactly one Marshal payload (success or error).
+  # The parent reads until EOF and parses it.
+  module Pipe
+    def self.write_result(io, value)
+      io.write(Marshal.dump({ status: :ok, value: value }))
+    end
+
+    def self.write_error(io, exception)
+      io.write(Marshal.dump({
+                              status: :error,
+                              class: exception.class.name,
+                              message: exception.message,
+                              backtrace: exception.backtrace
+                            }))
+    end
+
+    def self.read_result(raw)
+      return nil if raw.nil? || raw.empty?
+
+      Marshal.load(raw)
+    end
+  end
+end

data/lib/agent_jail/platform.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module AgentJail
+  module Platform
+    def self.linux?
+      RUBY_PLATFORM.include?("linux")
+    end
+
+    def self.macos?
+      RUBY_PLATFORM.include?("darwin")
+    end
+
+    def self.windows?
+      RUBY_PLATFORM.match?(/mingw|mswin|cygwin/)
+    end
+
+    def self.fork_supported?
+      linux? || macos?
+    end
+
+    def self.landlock_supported?
+      return false unless linux?
+
+      kernel_version >= Gem::Version.new("5.13")
+    end
+
+    def self.kernel_version
+      return Gem::Version.new("0.0") unless linux?
+
+      read_kernel_version
+    end
+
+    def self.read_kernel_version
+      content = File.read("/proc/version")
+      match = content.match(/Linux version (\d+\.\d+)/)
+      match ? Gem::Version.new(match[1]) : Gem::Version.new("0.0")
+    rescue StandardError
+      Gem::Version.new("0.0")
+    end
+    private_class_method :read_kernel_version
+  end
+end

data/lib/agent_jail/restrictions/base.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module AgentJail
+  module Restrictions
+    # Base interface for all restriction strategies.
+    # Each subclass implements #apply which is called in the child process
+    # before the sandboxed block runs.
+    class Base
+      def apply
+        raise NotImplementedError, "#{self.class}#apply not implemented"
+      end
+    end
+  end
+end

data/lib/agent_jail/restrictions/landlock.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module AgentJail
+  module Restrictions
+    # Applies Linux Landlock filesystem restrictions in the child process.
+    # Requires kernel 5.13+ and is a no-op on older kernels.
+    class Landlock < Base
+      # Paths that are implicitly allowed read-only for Ruby to function.
+      # These are added automatically regardless of user-specified fs_allow.
+      SYSTEM_READ_PATHS = %w[
+        /usr
+        /lib
+        /lib64
+        /proc
+        /dev
+        /etc
+        /run/systemd
+      ].freeze
+
+      def initialize(fs_allow:, fs_read_allow:)
+        super()
+        @fs_allow      = Array(fs_allow)
+        @fs_read_allow = Array(fs_read_allow)
+      end
+
+      def apply
+        ruleset_fd = FFI::Landlock.create_ruleset(FFI::Landlock::ALL_ACCESS_FS)
+        raise "landlock_create_ruleset failed: #{ruleset_fd}" if ruleset_fd.negative?
+
+        add_read_only_paths(ruleset_fd)
+        add_read_write_paths(ruleset_fd)
+
+        FFI::Landlock.restrict_self(ruleset_fd)
+      end
+
+      private
+
+      def add_read_only_paths(ruleset_fd)
+        (SYSTEM_READ_PATHS + @fs_read_allow).each do |path|
+          add_rule(ruleset_fd, path, FFI::Landlock::ACCESS_FS_READ_ONLY)
+        end
+      end
+
+      def add_read_write_paths(ruleset_fd)
+        @fs_allow.each do |path|
+          add_rule(ruleset_fd, path, FFI::Landlock::ACCESS_FS_READ_WRITE)
+        end
+      end
+
+      def add_rule(ruleset_fd, path, access_mask)
+        return unless File.exist?(path)
+
+        File.open(path) do |f|
+          result = FFI::Landlock.add_path_rule(ruleset_fd, f.fileno, access_mask)
+          # Negative return means the syscall failed; we ignore ENOENT/ENOTDIR silently
+          result
+        end
+      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+        # Path doesn't exist or can't be opened — skip it
+        nil
+      end
+    end
+  end
+end

data/lib/agent_jail/restrictions/resource_limits.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AgentJail
+  module Restrictions
+    # Applies POSIX resource limits (setrlimit) in the child process.
+    # Sets both address space (RLIMIT_AS) and CPU time (RLIMIT_CPU).
+    class ResourceLimits < Base
+      def initialize(memory_mb:, cpu_timeout:)
+        super()
+        @memory_bytes = memory_mb * 1024 * 1024
+        @cpu_timeout  = cpu_timeout
+      end
+
+      def apply
+        AgentJail::FFI::Setrlimit.set_memory(@memory_bytes)
+        AgentJail::FFI::Setrlimit.set_cpu(@cpu_timeout)
+      end
+    end
+  end
+end

data/lib/agent_jail/restrictions/seatbelt.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module AgentJail
+  module Restrictions
+    # Applies macOS Seatbelt (sandbox_init) filesystem restrictions in the child process.
+    class Seatbelt < Base
+      SYSTEM_READ_PATHS = %w[
+        /usr
+        /Library
+        /System
+        /private/var/db/dyld
+        /private/etc
+        /dev
+        /proc
+      ].freeze
+
+      def initialize(fs_allow:, fs_read_allow:)
+        super()
+        @fs_allow      = Array(fs_allow)
+        @fs_read_allow = Array(fs_read_allow)
+      end
+
+      def apply
+        return unless FFI::Seatbelt::AVAILABLE
+
+        profile = build_profile
+        errorbuf_ptr = ::FFI::MemoryPointer.new(:pointer)
+        result = FFI::Seatbelt.sandbox_init(profile, 0, errorbuf_ptr)
+
+        return unless result != 0
+
+        err_ptr = errorbuf_ptr.read_pointer
+        message = err_ptr.null? ? "sandbox_init failed" : err_ptr.read_string
+        FFI::Seatbelt.sandbox_free_error(err_ptr) unless err_ptr.null?
+        raise "sandbox_init failed: #{message}"
+      end
+
+      private
+
+      def build_profile
+        lines = ["(version 1)", "(deny default)"]
+
+        SYSTEM_READ_PATHS.each do |path|
+          lines << "(allow file-read* (subpath \"#{path}\"))"
+        end
+
+        @fs_read_allow.each do |path|
+          lines << "(allow file-read* (subpath \"#{path}\"))"
+        end
+
+        @fs_allow.each do |path|
+          lines << "(allow file-read-write* (subpath \"#{path}\"))"
+        end
+
+        lines << "(allow process-exec*)"
+        lines << "(allow mach*)"
+        lines << "(allow sysctl*)"
+        lines << "(allow signal)"
+        lines << "(allow network* (local))"
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/agent_jail/runner.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module AgentJail
+  # Orchestrates the fork + pipe + monitor pattern.
+  # Forks a child, applies a wall-clock timeout monitor thread, reads the result.
+  class Runner
+    def initialize(options, &block)
+      cfg = AgentJail.configuration
+      @timeout     = options.fetch(:timeout, cfg.default_timeout)
+      @cpu_timeout = options.fetch(:cpu_timeout, @timeout)
+      @memory_mb   = options.fetch(:memory_mb, cfg.default_memory_mb)
+      @fs_allow    = options.fetch(:fs_allow, cfg.default_fs_allow)
+      @fs_read_allow = options.fetch(:fs_read_allow, [])
+      @block = block
+    end
+
+    def call
+      read, write = IO.pipe
+
+      child_pid = fork do
+        read.close
+        Child.new(
+          write: write,
+          cpu_timeout: @cpu_timeout,
+          memory_mb: @memory_mb,
+          fs_allow: @fs_allow,
+          fs_read_allow: @fs_read_allow,
+          block: @block
+        ).run
+        exit!(0)
+      end
+
+      write.close
+      raw, status = wait_for_child(read, child_pid)
+      read.close
+
+      parse_result(raw, status)
+    end
+
+    private
+
+    def wait_for_child(read_io, child_pid)
+      monitor = Thread.new do
+        sleep(@timeout)
+        Process.kill(:KILL, child_pid)
+      rescue Errno::ESRCH
+        # Child already exited before wall-clock timeout — no-op
+      end
+
+      raw = read_io.read
+      _pid, status = Process.waitpid2(child_pid)
+      monitor.kill
+      monitor.join
+
+      [raw, status]
+    end
+
+    def parse_result(raw, status)
+      result = Pipe.read_result(raw)
+      return raise_from_result(result) if result
+
+      # Pipe was empty — child was killed before writing
+      raise_from_signal(status)
+    end
+
+    def raise_from_result(result)
+      case result[:status]
+      when :ok
+        result[:value]
+      when :error
+        klass = result[:class]
+        if filesystem_error?(klass)
+          raise FilesystemError, result[:message]
+        elsif memory_error?(klass)
+          raise MemoryError, result[:message]
+        else
+          raise SandboxError.new(
+            original_class: klass,
+            original_message: result[:message],
+            original_backtrace: result[:backtrace]
+          )
+        end
+      end
+    end
+
+    def raise_from_signal(status)
+      raise MemoryError, "Process exceeded #{@memory_mb}MB memory limit" unless status.signaled?
+
+      sig = status.termsig
+      case sig
+      when Signal.list["XCPU"]
+        raise TimeoutError, "Process exceeded #{@cpu_timeout}s CPU time limit"
+      when Signal.list["SEGV"]
+        raise MemoryError, "Process exceeded #{@memory_mb}MB memory limit (SIGSEGV)"
+      else
+        # SIGKILL (9) — sent by our monitor thread (wall-clock) or OS OOM killer
+        raise TimeoutError, "Process exceeded #{@timeout}s wall-clock timeout"
+      end
+    end
+
+    def filesystem_error?(klass)
+      %w[Errno::EACCES Errno::EPERM AgentJail::FilesystemError].include?(klass)
+    end
+
+    def memory_error?(klass)
+      %w[NoMemoryError AgentJail::MemoryError].include?(klass)
+    end
+  end
+end

data/lib/agent_jail/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentJail
+  VERSION = "0.1.0"
+end

data/lib/agent_jail.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "agent_jail/version"
+require "agent_jail/configuration"
+require "agent_jail/errors"
+require "agent_jail/platform"
+require "agent_jail/pipe"
+require "agent_jail/ffi/setrlimit"
+require "agent_jail/restrictions/base"
+require "agent_jail/restrictions/resource_limits"
+require "agent_jail/child"
+require "agent_jail/runner"
+
+if AgentJail::Platform.linux?
+  require "agent_jail/ffi/landlock"
+  require "agent_jail/restrictions/landlock"
+end
+
+# Seatbelt files load on all platforms — ffi/seatbelt.rb sets AVAILABLE = false
+# when libsandbox is not present, and Restrictions::Seatbelt#apply is a no-op then.
+require "agent_jail/ffi/seatbelt"
+require "agent_jail/restrictions/seatbelt"
+
+module AgentJail
+  class << self
+    def configure
+      yield configuration
+      configuration.validate!
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset!
+      @configuration = nil
+    end
+
+    # Run a block inside a sandboxed child process with resource limits and
+    # optional filesystem restrictions.
+    #
+    # @param timeout [Integer] wall-clock timeout in seconds (default: 30)
+    # @param cpu_timeout [Integer] CPU time limit in seconds (default: same as timeout)
+    # @param memory_mb [Integer] address space limit in MB (default: 512)
+    # @param fs_allow [Array<String>] read-write paths the child may access
+    # @param fs_read_allow [Array<String>] read-only paths the child may access
+    # @return the block's return value
+    def run(**options, &block)
+      raise ArgumentError, "block required" unless block
+
+      unless Platform.fork_supported?
+        handle_unsupported("Sandboxing is not supported on #{RUBY_PLATFORM}")
+        return block.call
+      end
+
+      Runner.new(options, &block).call
+    end
+
+    private
+
+    def handle_unsupported(reason)
+      case configuration.on_unsupported
+      when :raise
+        raise UnsupportedPlatformError, reason
+      when :warn
+        warn "[AgentJail] WARNING: #{reason}. Running block unsandboxed."
+      when :ignore
+        nil
+      end
+    end
+  end
+end

data/sig/agent_jail.rbs

@@ -0,0 +1,41 @@
+module AgentJail
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class TimeoutError < Error
+  end
+
+  class MemoryError < Error
+  end
+
+  class FilesystemError < Error
+  end
+
+  class UnsupportedPlatformError < Error
+  end
+
+  class SandboxError < Error
+    attr_reader original_class: String
+    attr_reader original_message: String
+    attr_reader original_backtrace: Array[String]?
+
+    def initialize: (original_class: String, original_message: String, original_backtrace: Array[String]?) -> void
+  end
+
+  class Configuration
+    attr_accessor default_timeout: Integer
+    attr_accessor default_memory_mb: Integer
+    attr_accessor default_fs_allow: Array[String]
+    attr_accessor on_unsupported: Symbol
+
+    def initialize: () -> void
+    def validate!: () -> void
+  end
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.reset!: () -> void
+  def self.run: (?timeout: Integer, ?cpu_timeout: Integer, ?memory_mb: Integer, ?fs_allow: Array[String], ?fs_read_allow: Array[String]) { () -> untyped } -> untyped
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: agent_jail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jibran Usman
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |-
+  Forks a child process, applies Linux Landlock filesystem restrictions and POSIX resource limits
+  (setrlimit), then runs your block. If the block times out, exceeds memory, or touches a disallowed
+  path, the child is killed and the parent gets a typed exception. macOS uses Seatbelt (sandbox_init).
+  Degrades gracefully on unsupported platforms.
+email:
+- jibran.usman@eunasolutions.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/agent_jail.rb
+- lib/agent_jail/child.rb
+- lib/agent_jail/configuration.rb
+- lib/agent_jail/errors.rb
+- lib/agent_jail/ffi/landlock.rb
+- lib/agent_jail/ffi/seatbelt.rb
+- lib/agent_jail/ffi/setrlimit.rb
+- lib/agent_jail/pipe.rb
+- lib/agent_jail/platform.rb
+- lib/agent_jail/restrictions/base.rb
+- lib/agent_jail/restrictions/landlock.rb
+- lib/agent_jail/restrictions/resource_limits.rb
+- lib/agent_jail/restrictions/seatbelt.rb
+- lib/agent_jail/runner.rb
+- lib/agent_jail/version.rb
+- sig/agent_jail.rbs
+homepage: https://github.com/jibranusman95/agent_jail
+licenses: []
+metadata:
+  homepage_uri: https://github.com/jibranusman95/agent_jail
+  source_code_uri: https://github.com/jibranusman95/agent_jail
+  changelog_uri: https://github.com/jibranusman95/agent_jail/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'Sandbox LLM tool calls in a child process: timeout, memory, and filesystem
+  limits.'
+test_files: []