rails-mcp-server 1.5.1 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bb5fa61d56e0b92152a67a191cb7f0e0742496cf96d462467fefe40f201efec
-  data.tar.gz: ba1ead2d4cecc46770c94e44704536453ce12ffada3882d71da8f47ef9ff0e43
+  metadata.gz: 950673f40d56ddea684d938e4e55c2e8db18c3ca44e94988f63565a9db950869
+  data.tar.gz: 00712156bdfdfbfc1ec33bd08e31ccb0ad4e7427e3e1e31282de62b4f7b5cc1b
 SHA512:
-  metadata.gz: 86a0f66633dfce8adf6f3b929906a044502696bf0f2a14d054dfa8b8db7984f5962373e1fe2149557eccd149d9a31cbb2437fd52a75fa4f27e32d14099ba67b8
-  data.tar.gz: 393d684c4695480de7111c27cad29bf3ef9e69d748d1c94212b1861576479bac34ba43f2955006d3510f30d1285a304ce5c84a30863893c21de97817eff0fa73
+  metadata.gz: 98ebb4452eaa610b1430c652c94a339022f10bc05ba7a00b867e8b8c9aaa04d033ea149d923bfe131be52455b044b0feb4d90af24a55670708610e2a57b198a1
+  data.tar.gz: 8ecf71ec6b09ed73b35e6f9ea64ec88bfcbbf1f91e2bbb8f033216d0a19d0c6af1493c23fb67be14f99e7933cc6dcc7d64f09d173d20c8c2d6a53f4d25ef88ef

data/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.6.1] - 2026-08-04
+
+### Security
+
+- **`execute_ruby` process-execution hardening**: Closed a command-execution path and tightened the static filter.
+  - **`require` restricted to a tiny data-lib allowlist**: `require_relative` and dynamic `require`s are refused, and literal `require "lib"` is refused except for a small allowlist of pure-data libraries not always preloaded (`csv`, `tzinfo`, `date`, `time`). Under `bin/rails runner` the app's models, ActiveRecord, and the stdlib Rails loads on boot are already available, so inspection code needs almost no requires — and every dangerous stdlib escape has to be required first. This closes `require "pty"` (`PTY.spawn`/`PTY.getpty` started a child process outside the `Kernel#system` guard, giving arbitrary host command execution), along with `open3`, `fiddle`, `ffi`, and `socket`, at the source rather than by enumerating individual APIs. (`tzinfo` pairs with the existing system-timezone read-path allowlist so `Time.zone` code keeps working.)
+  - **Native/PTY patterns**: `PTY`, `Fiddle`, and `FFI` are added to the forbidden-pattern scan as defense in depth.
+  - **Dynamic dispatch to execution sinks hard-blocked**: `send`/`public_send`/`__send__`/`const_get` aimed by name at an execution or eval sink (`system`, `exec`, `spawn`, `fork`, `eval`, `popen`, `Open3`, `Process`, `PTY`, …) are now rejected outright instead of merely gated behind `confirm_risky`. Benign dynamic dispatch (e.g. `record.send(:name)`) is unaffected.
+  - **Honest framing**: the tool description and docs no longer call `execute_ruby` a read-only sandbox. It runs caller-supplied Ruby with the privileges of the server process; the controls are best-effort guardrails, not an isolation boundary.
+
+### Fixed
+
+- **ReDoS in the `execute_ruby` static scan**: Rewrote the `require`/dynamic-dispatch matchers to remove an ambiguous `\s*\(?\s*` construct that backtracked in polynomial time on adversarial whitespace input (CodeQL alert). Matching is now linear.
+
+## [1.6.0] - 2026-08-03
+
+### Added
+
+- **Namespaced model resolution in `analyze_models`**: Module-namespaced models now resolve from every input form — `Namespace::Model`, the file path `namespace/model`, the flattened `NamespaceModel`, and the bare leaf `Model` — independent of the app's custom inflections. Previously namespaced models could be reported as "not found".
+
+### Changed
+
+- **Dropped Ruby 3.2 support** (breaking): The minimum supported Ruby is now 3.3 (`required_ruby_version >= 3.3.0`), and the CI matrix tests Ruby 3.3 and 3.4. Dependency updates pull in transitive gems (`dry-configurable` 1.4.0, `parallel` 2.1.0) that require Ruby >= 3.3.
+- **Dependency updates**: Bumped project dependencies, including major upgrades to `puma` (~> 8.0), `minitest` (~> 6.0) and `mocha` (~> 3.0), plus `activesupport` 8.1.3.1, `addressable` 2.9.0, `rubocop` 1.88.2, `standard` 1.56.0 and other transitive gems.
+- **Deterministic linting**: Added `.standard.yml` pinning `ruby_version: 3.3` to match the gemspec's minimum supported Ruby, so Standard/RuboCop target the supported floor regardless of the local or CI Ruby.
+
+### Fixed
+
+- **Version-manager Ruby resolution for Rails-runner tools** (mise/asdf/rbenv agnostic): Tools that shell out to `bin/rails` (`execute_ruby`, `get_schema`, and the introspection half of `analyze_models` / `analyze_controller_views`) no longer fall back to the system Ruby on machines managed by mise or asdf. The runner previously exported the rbenv-only `RBENV_VERSION` and used a login shell (`$SHELL -l -c`); on macOS `path_helper` then reordered `PATH` so `bin/rails` booted under system Ruby and failed. It now prepends the active manager's shims directory (mise/asdf/rbenv, honoring `MISE_DATA_DIR`/`XDG_DATA_HOME`/`ASDF_DATA_DIR`/`RBENV_ROOT`) to the subprocess `PATH` and runs a non-login shell, so the project's Ruby is used. rvm (which has no shims) is still sourced when present.
+- **`analyze_models` introspection constant**: The introspection runner now derives the canonical constant from the resolved model file (loaded via `Object.const_get`) instead of interpolating the raw user input. This fixes invalid-Ruby / `NameError` failures for path and flattened inputs, degrades non-ActiveRecord constants to a clear message, and removes an unvalidated-input injection surface in the generated runner scripts.
+- **Analyzer errors no longer swallowed**: The analyzer runner path dropped `2>/dev/null`, so a Rails boot failure now surfaces the real error instead of a blank "Error executing Rails command".
+- **`execute_ruby` timezone data access**: The sandbox now allows read-only access to system timezone directories (`/usr/share/zoneinfo`, `/usr/share/lib/zoneinfo`, `/etc/zoneinfo`, `/var/db/timezone`). Previously, any code that touched `Time.zone` failed with `PATH ERROR: Access denied: path '/usr/share/zoneinfo/...' is outside project directory` because TZInfo lazily loads IANA timezone data on first use. Writes and all other out-of-project reads remain blocked.
+
+### Security
+
+- **`execute_ruby` sandbox hardening**: Closed several read-path bypasses and added defense-in-depth layers to the sandbox.
+  - **File-read coverage**: `IO.read`/`readlines`/`binread`/`foreach` and `File.readlines`/`binread`/`foreach` are now sandboxed too (previously only `File.read`/`open` were, so `IO.read('/etc/passwd')` and `File.readlines` bypassed path validation). The raw native readers are no longer exposed as public `File.original_read`-style aliases.
+  - **Symlink resolution**: path validation now resolves symlinks (`realpath`) before checking, so a link inside the project can't point outside it. The system-timezone allowlist is matched against canonical (symlink-resolved) locations so it keeps working on macOS.
+  - **Broader `ENV` block**: the static scan now rejects all `ENV` access (`ENV.to_h`, `ENV.values_at`, `ENV.each`, …), not just `ENV[]`/`ENV.fetch`.
+  - **Database writes rolled back**: user code runs inside a transaction that is always rolled back, so accidental `delete_all`/`update`/`save`/raw DML are undone. (Harm reduction — DDL may auto-commit on some adapters and `after_commit` callbacks are suppressed.)
+  - **Timeout actually stops runaway code**: the execution timeout now kills the entire process group, so a runaway `bin/rails runner` is terminated instead of being orphaned while the parent stops waiting.
+  - **Confirmation for dual-use constructs**: `send`, `public_send`, `const_get`, and `Kernel#open` are no longer run implicitly. The tool returns a `CONFIRMATION REQUIRED` message; callers must opt in with the new `confirm_risky: true` parameter after a human reviews the code.
+- **Puma advisories resolved**: Upgrading to `puma` 8.0.2 addresses CVE-2026-47736 and CVE-2026-47737 (both HIGH — PROXY Protocol v1 remote memory exhaustion and repeated-header handling). Dependency updates also clear the `concurrent-ruby` ReadWriteLock advisory (GHSA-6wx8-w4f5-wwcr). `bundler-audit` now reports no vulnerabilities.
+
 ## [1.5.1] - 2026-03-04
 
 ### Changed
@@ -323,6 +369,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version History Summary
 
+- **v1.6.1** (2026-08-04): `execute_ruby` process-execution hardening (blocks the `require "pty"` → `PTY.spawn` command-execution path, restricts `require` to a data-lib allowlist, hard-blocks dynamic dispatch to execution sinks) and a ReDoS fix in the static scan
+- **v1.6.0** (2026-08-03): Sandbox hardening for `execute_ruby`, version-manager Ruby resolution, namespaced model resolution, dependency + security updates (drops Ruby 3.2)
 - **v1.5.1** (2026-03-04): Relaxed dependency version constraints for better compatibility
 - **v1.4.0** (2025-12-10): Context-efficient architecture with progressive tool discovery (67% token reduction)
 - **v1.2.3** (2025-12-10): Setup script fix for readonly filesystems (NixOS compatibility)

data/README.md

@@ -17,7 +17,7 @@ This Rails MCP Server implements the MCP specification to give AI models access
 - Get database schema information
 - Analyze controller-view relationships
 - Analyze environment configurations
-- Execute sandboxed Ruby code for custom queries
+- Execute Ruby code in the project context for custom queries
 - Access comprehensive Rails, Turbo, Stimulus, and Kamal documentation
 - Context-efficient architecture with progressive tool discovery
 - Seamless integration with LLM clients
@@ -207,9 +207,11 @@ After running the script, restart Claude Desktop to apply the changes.
 
 ### Ruby Version Manager Users
 
-Claude Desktop launches the MCP server using your system's default Ruby environment, bypassing version manager initialization (e.g., rbenv, RVM). The MCP server needs to use the same Ruby version where it was installed, as MCP server startup failures can occur when using an incompatible Ruby version.
+Two different Rubies are involved, and the server handles them differently.
 
-If you are using a Ruby version manager such as rbenv, you can use the Ruby shim path to ensure the correct version is used:
+#### 1. The Ruby that runs the MCP server
+
+Your MCP client (e.g. Claude Desktop) launches the server using your system's default Ruby, bypassing version-manager initialization. The server must run on the Ruby where its gem is installed, or startup fails. Point the client's `command` at that Ruby's absolute path — for a version manager, its shim works:
 
 ```json
 {
@@ -222,9 +224,15 @@ If you are using a Ruby version manager such as rbenv, you can use the Ruby shim
 }
 ```
 
-Replace "/home/your_user/.rbenv/shims/ruby" with your actual path for the Ruby shim.
+Replace `/home/your_user/.rbenv/shims/ruby` with your actual Ruby path (an rbenv/mise/asdf shim, or your `rvm`/`chruby` Ruby).
+
+**Tip**: The `rails-mcp-config` tool detects this Ruby automatically (via `RbConfig.ruby`) and writes the correct absolute path when configuring Claude Desktop.
+
+#### 2. The Ruby used to introspect each Rails project
 
-**Tip**: The `rails-mcp-config` tool automatically detects your Ruby path and uses the correct shim path when configuring Claude Desktop.
+Tools that boot your app — `execute_ruby`, `get_schema`, and the introspection half of `analyze_models` / `analyze_controller_views` — run `bin/rails` inside the project directory. The server selects the **project's** Ruby automatically and is agnostic to your version manager: it prepends the active manager's shims (**mise**, **asdf**, **rbenv**) to the subprocess `PATH` and sources **rvm** when present, then uses a non-login shell so macOS `path_helper` cannot substitute the system Ruby. The version is taken from the project's `.ruby-version` / `.tool-versions` / `.mise.toml`, so different projects can use different Rubies with no extra configuration.
+
+> No manual `PATH` workaround is needed. Previously these tools could fall back to the system Ruby on mise/asdf machines, where the app's Bundler then failed to boot.
 
 ### Using an MCP Proxy (Advanced)
 
@@ -352,7 +360,7 @@ The server uses a progressive tool discovery architecture to minimize context us
 - **`switch_project`** - Select the active Rails project
 - **`search_tools`** - Discover available tools by category or keyword
 - **`execute_tool`** - Invoke internal analyzers with parameters
-- **`execute_ruby`** - Run sandboxed Ruby code for custom queries
+- **`execute_ruby`** - Run Ruby code in the project context for custom queries
 
 This design reduces initial context from ~2,400 tokens to ~800 tokens while maintaining full functionality.
 
@@ -404,12 +412,13 @@ After switching, you'll see a Quick Start guide with common commands.
 
 #### 4. `execute_ruby`
 
-**Description:** Execute sandboxed Ruby code in the Rails project context.
+**Description:** Execute Ruby code in the Rails project context, for inspection and exploration. Runs with the privileges of the server process — see the Security note below; this is not a sandbox for untrusted code.
 
 **Parameters:**
 
 - `code`: (String, required) Ruby code to execute
 - `timeout`: (Integer, optional) Timeout in seconds (default: 30, max: 60)
+- `confirm_risky`: (Boolean, optional) Set `true` only after you have explicitly approved code that uses dual-use constructs (`send`, `public_send`, `const_get`, `Kernel#open`). When false/absent, such code is not executed — the tool returns a `CONFIRMATION REQUIRED` message explaining the risk instead.
 
 **Available helper methods:**
 
@@ -420,7 +429,21 @@ After switching, you'll see a Quick Start guide with common commands.
 
 **Note:** Use `puts` to see output from your code.
 
-**Security:** The sandbox prevents file writes, system calls, network access, and reading sensitive files (.env, credentials, etc.).
+**Security:** `execute_ruby` runs Ruby that you — or your coding agent — supply, inside your Rails application, with the privileges of the process that started the server. **It is not a security sandbox for untrusted code.** The guardrails below reduce accidental damage and block the obvious escapes, but real Ruby is expressive enough that a determined caller can work around a pattern-based filter; treat the controls as defense-in-depth, not an isolation boundary.
+
+Because you start the server yourself — normally locally, against your own project — the realistic risk is *running code you didn't intend to*, for example when a coding agent is steered by prompt injection into calling `execute_ruby` with a hostile payload. That payload would run as you. So: only enable this tool for projects and clients you trust, and actually review code before approving a `confirm_risky` re-run.
+
+Guardrails applied:
+
+- **No writes / shell / network:** file writes, `system`/`exec`/backticks/`spawn`, and network libraries are blocked by both static analysis and runtime overrides.
+- **Almost no `require`:** `require_relative` and dynamic `require`s are refused, and `require "lib"` is refused for everything except a tiny allowlist of pure-data libraries (`csv` and the timezone libs) that Rails doesn't always preload. Under `bin/rails runner` the app's models, ActiveRecord, and the stdlib Rails loads on boot (`json`, `yaml`, `set`, `date`, …) are already available, so inspection code needs no requires anyway — and every dangerous stdlib escape (`pty`, `open3`, `fiddle`, `ffi`, `socket`) has to be required first, so refusing them removes that whole class of bypass at the source.
+- **Confined file reads:** reads are limited to the project directory (via all of `File`/`IO` `read`/`readlines`/`binread`/`foreach` and `File.open`), plus a small allowlist of read-only system timezone paths (e.g. `/usr/share/zoneinfo`) that Rails needs when code touches `Time.zone`. Paths are symlink-resolved (`realpath`) so a link inside the project cannot point outside it.
+- **No sensitive files:** `.env`, credentials, keys, and any `.gitignore`d path are refused.
+- **Database writes are rolled back:** user code runs inside a transaction that is always rolled back, so `delete_all`, `update`, `save`, and raw DML are undone — a safety net against accidental mutation, not a data-access guarantee. (Caveat: DDL may still commit on some adapters such as MySQL, and `after_commit` callbacks do not fire.)
+- **Bounded execution:** a timeout (default 30s, max 60s) kills the whole process group, so a runaway `bin/rails runner` is terminated rather than orphaned.
+- **Dynamic dispatch to execution sinks is hard-blocked:** `send`/`public_send`/`const_get` aimed by name at `system`/`exec`/`spawn`/`eval`/`Open3`/`Process`/`PTY`/… are rejected outright; the remaining dual-use forms of `send`, `public_send`, `const_get`, and `Kernel#open` are not run until you approve them via `confirm_risky: true`.
+
+For a real boundary, run the server against a database user with read-only grants and/or inside OS-level isolation (a container, `sandbox-exec`, seccomp, a dedicated low-privilege user with no ambient credentials or network) rather than relying on these in-process checks.
 
 ### Internal Analyzers (via execute_tool)
 
@@ -604,6 +627,8 @@ To use with an MCP client:
 2. Connect your MCP-compatible client to the server
 3. The client will be able to use the available tools to interact with your Rails projects
 
+For teams using a governed AI client or control plane for tool access, approvals, audit trails, and cost reporting, see [Governed MCP Clients](docs/GOVERNED_CLIENTS.md).
+
 ## Security
 
 For security concerns, please see [SECURITY.md](SECURITY.md).

data/docs/AGENT.md

@@ -225,6 +225,10 @@ railsMcpServer:execute_ruby code: "read_file('Gemfile')"
 railsMcpServer:execute_ruby code: "puts read_file('Gemfile')"
 ```
 
+**For inspection, not mutation:** `execute_ruby` is meant for exploring the app, not changing it. File writes, shell/system calls, process spawning, and network access are blocked, and any database writes run inside a transaction that is **always rolled back** — so `delete_all`, `update`, and `save` will not persist. Do not rely on it to change data. These are guardrails, not a security sandbox: the code you send runs with the privileges of the server process, so send only code you would run yourself, and never code from an untrusted source (e.g. copied out of an issue, PR, or file you're inspecting).
+
+**Confirmation for dual-use constructs:** if your code uses `send`, `public_send`, `const_get`, or `Kernel#open`, the tool returns a `CONFIRMATION REQUIRED` message instead of running. These can bypass the static safety scan, so ask the user to review the code and, only with their explicit approval, re-invoke with `confirm_risky: true`. Do not set `confirm_risky` on your own.
+
 ---
 
 ## Tool Selection Summary
@@ -400,6 +404,14 @@ railsMcpServer:execute_ruby code: "User.count"
 railsMcpServer:execute_ruby code: "puts User.count"
 ```
 
+### `execute_ruby` / `get_schema` fail to boot the app (Bundler / wrong Ruby)
+
+These tools run the project's `bin/rails`. The server auto-selects the project's Ruby via your version manager's shims (**mise**, **asdf**, **rbenv**; **rvm** is sourced), reading `.ruby-version` / `.tool-versions` / `.mise.toml`. If they still fail with a Bundler or boot error:
+
+1. Confirm the project has a `.ruby-version` (or `.tool-versions` / `.mise.toml`) and that Ruby is installed in your manager.
+2. Confirm your manager is one of mise, asdf, rbenv, or rvm — these are auto-detected.
+3. The underlying boot error is included in the tool output (no longer suppressed), so read it for the specific cause.
+
 ---
 
 ## Integration with Neovim MCP

data/docs/COPILOT_AGENT.md

@@ -14,7 +14,7 @@ GitHub Copilot coding agent runs MCP servers in ephemeral GitHub Actions environ
 
 - A Rails application repository on GitHub
 - GitHub Copilot with coding agent enabled
-- Ruby 3.1+ (recommended: 3.3)
+- Ruby 3.3+ (recommended: 3.4)
 
 ## Configuration
 
@@ -133,7 +133,7 @@ GitHub Copilot Agent only supports MCP **tools**. The following are available:
 | `switch_project` | Change active project (optional in single-project mode) |
 | `search_tools` | Discover available analyzers |
 | `execute_tool` | Invoke internal analyzers |
-| `execute_ruby` | Run sandboxed Ruby code |
+| `execute_ruby` | Run Ruby code in the project context |
 
 ### Internal Analyzers (via `execute_tool`)
 
@@ -171,7 +171,7 @@ The `load_guide` analyzer requires guides to be downloaded. To include guides:
 
 ### Network Restrictions
 
-GitHub Copilot Agent runs in a sandboxed environment with firewall restrictions. The MCP server has read-only access to the repository.
+GitHub Copilot Agent runs in a sandboxed environment with firewall restrictions. The MCP server is used here to inspect the repository and runs with the permissions of that agent environment; note that `execute_ruby` executes real Ruby with those permissions and is not itself an isolation boundary (see the [security notes](../README.md#4-execute_ruby)).
 
 ## Troubleshooting
 

data/docs/GOVERNED_CLIENTS.md

@@ -0,0 +1,44 @@
+# Governed MCP Clients
+
+Rails MCP Server exposes Rails project tools and documentation resources through the Model Context Protocol. Some teams connect those MCP tools to a governed AI client or control plane so tool access, audit trails, approvals, and cost controls can be managed centrally.
+
+This guide describes the integration pattern. Rails MCP Server continues to own the Rails project tools and resources. The governed client or gateway owns model access, policy decisions, and cross-application reporting.
+
+## Pattern
+
+1. Start Rails MCP Server in STDIO or HTTP mode.
+2. Register the server with an MCP-compatible client or control plane.
+3. Let the client decide which users, roles, or agents can call Rails MCP tools.
+4. Keep Rails project paths and credentials local to the Rails MCP Server environment.
+
+## Example: Tuning Engines
+
+Tuning Engines can be used as a governed AI control plane in front of model, agent, and MCP workflows. In this setup:
+
+- Rails MCP Server provides tools such as `switch_project`, `search_tools`, `execute_tool`, and `load_guide`.
+- The MCP client or control plane registers the Rails MCP Server and discovers its tools.
+- Tuning Engines can enforce tenant, role, or policy-based access to MCP tools and record traces/costs for model and tool activity.
+
+For local development, start Rails MCP Server normally:
+
+```bash
+rails-mcp-server
+```
+
+For HTTP/SSE testing or a local proxy:
+
+```bash
+rails-mcp-server --mode http
+```
+
+Then configure your MCP-compatible client or control plane to connect to the STDIO command or HTTP/SSE endpoint.
+
+## Security notes
+
+- Do not expose Rails MCP Server on an untrusted network.
+- Prefer STDIO or localhost HTTP mode unless you have a trusted network and explicit access controls.
+- Keep Rails project paths, credentials, and `.env` files local to the server.
+- Use the governed client to restrict high-risk tools such as code execution or broad project scans.
+- Preserve request IDs or trace IDs in client metadata when available so tool calls can be correlated with model calls.
+
+This pattern is useful when Rails MCP Server is part of a larger production AI workflow and the organization needs compliance, control, and cost reporting outside individual MCP clients.

data/exe/rails-mcp-config

@@ -219,8 +219,8 @@ module RailsMcpConfig
         print Colors.mauve(Colors.bold("#{prompt} "))
         print Colors.dim("[#{default_value}] ") unless default_value.empty?
         result = gets&.strip
-        return default_value if result&.empty? && !default_value.empty?
-        result&.empty? ? nil : result
+        return default_value if result == "" && !default_value.empty?
+        (result == "") ? nil : result
       end
     end
 
@@ -1151,6 +1151,7 @@ module RailsMcpConfig
 
       ui.info("Ruby executable: #{ruby_path}")
       ui.info("Server executable: #{server_path}")
+      ui.info("Rails introspection uses each project's own Ruby (mise/asdf/rbenv/rvm) automatically.")
       puts
 
       return unless ui.confirm("Apply this configuration?", default: true)

data/lib/rails-mcp-server/analyzers/analyze_models.rb

@@ -60,24 +60,32 @@ module RailsMcpServer
 
             Tips:
             - Use CamelCase: 'User', 'BlogPost', 'OrderItem'
+            - For namespaced models use 'Namespace::Model' or the file path 'namespace/model'
             - Use singular form: 'User' not 'Users'
             - Run analyze_models without params to list all models
           ERROR
         end
 
+        # Resolve the canonical constant from the file we actually found, rather
+        # than trusting the raw input. This lets namespaced ("Base::FundHolding"),
+        # path ("base/fund_holding") and flattened ("BaseFundHolding") inputs all
+        # produce a valid Ruby constant for the introspection runner, and keeps
+        # unvalidated user input out of the interpolated script.
+        class_name = model_class_name(model_file)
+
         case detail_level
         when "names"
-          "Model: #{model_name}\nFile: #{model_file.sub(active_project_path + "/", "")}"
+          "Model: #{class_name}\nFile: #{model_file.sub(active_project_path + "/", "")}"
         when "associations"
-          format_associations_only(model_name, model_file)
+          format_associations_only(class_name, model_file)
         else
-          build_full_analysis(model_name, model_file, analysis_type)
+          build_full_analysis(class_name, model_file, analysis_type)
         end
       end
 
-      def format_associations_only(model_name, model_file)
-        associations = get_associations_via_introspection(model_name)
-        output = ["Model: #{model_name}", "File: #{model_file.sub(active_project_path + "/", "")}", "", "Associations:"]
+      def format_associations_only(class_name, model_file)
+        associations = get_associations_via_introspection(class_name)
+        output = ["Model: #{class_name}", "File: #{model_file.sub(active_project_path + "/", "")}", "", "Associations:"]
         if associations&.any?
           associations.each { |a| output << "  #{a[:type]} :#{a[:name]}" }
         else
@@ -86,11 +94,11 @@ module RailsMcpServer
         output.join("\n")
       end
 
-      def build_full_analysis(model_name, model_file, analysis_type)
-        output = ["=" * 60, "Model: #{model_name}", "File: #{model_file.sub(active_project_path + "/", "")}", "=" * 60]
+      def build_full_analysis(class_name, model_file, analysis_type)
+        output = ["=" * 60, "Model: #{class_name}", "File: #{model_file.sub(active_project_path + "/", "")}", "=" * 60]
 
         if %w[introspection full].include?(analysis_type)
-          output << "" << introspection_analysis(model_name)
+          output << "" << introspection_analysis(class_name)
         end
 
         if %w[static full].include?(analysis_type)
@@ -101,8 +109,8 @@ module RailsMcpServer
         output.join("\n")
       end
 
-      def introspection_analysis(model_name)
-        script = build_introspection_script(model_name)
+      def introspection_analysis(class_name)
+        script = build_introspection_script(class_name)
         raw_output = execute_rails_runner(script)
         data = begin
           JSON.parse(extract_json(raw_output))
@@ -113,12 +121,15 @@ module RailsMcpServer
         format_introspection_result(data)
       end
 
-      def build_introspection_script(model_name)
+      def build_introspection_script(class_name)
         <<~RUBY
           require 'json'
           begin
-            model = #{model_name}
+            model = Object.const_get(#{class_name.inspect})
             result = {}
+            unless model.is_a?(Class) && model.respond_to?(:reflect_on_all_associations)
+              raise "\#{model} is not an ActiveRecord model"
+            end
             if model.respond_to?(:table_name) && model.table_exists?
               result[:table_name] = model.table_name
               result[:primary_key] = model.primary_key
@@ -238,8 +249,8 @@ module RailsMcpServer
         output.join("\n")
       end
 
-      def get_associations_via_introspection(model_name)
-        script = "require 'json'; puts (#{model_name}.reflect_on_all_associations.map { |a| { name: a.name.to_s, type: a.macro.to_s } } rescue []).to_json"
+      def get_associations_via_introspection(class_name)
+        script = "require 'json'; puts (Object.const_get(#{class_name.inspect}).reflect_on_all_associations.map { |a| { name: a.name.to_s, type: a.macro.to_s } } rescue []).to_json"
         begin
           JSON.parse(extract_json(execute_rails_runner(script))).map { |a| a.transform_keys(&:to_sym) }
         rescue
@@ -248,8 +259,39 @@ module RailsMcpServer
       end
 
       def find_model_file(model_name)
-        path = File.join(active_project_path, "app", "models", "#{underscore(model_name)}.rb")
-        File.exist?(path) ? path : Dir.glob(File.join(active_project_path, "app", "models", "**", "#{underscore(model_name).split("/").last}.rb")).first
+        models_dir = File.join(active_project_path, "app", "models")
+        return nil unless File.directory?(models_dir)
+
+        # Fast path: conventional inflection (Base::FundHolding -> base/fund_holding.rb).
+        direct = File.join(models_dir, "#{underscore(model_name)}.rb")
+        return direct if File.exist?(direct)
+
+        # Fallback: match against the files that actually exist so namespaced,
+        # path, flattened and bare-leaf forms all resolve, independent of any
+        # custom inflections the app registers. Prefer a full relative-path
+        # match; only then fall back to a bare filename (leaf) match.
+        files = Dir.glob(File.join(models_dir, "**", "*.rb"))
+        target = model_key(model_name)
+
+        files.find { |file| model_key(relative_model_path(file, models_dir)) == target } ||
+          files.find { |file| model_key(File.basename(file, ".rb")) == target }
+      end
+
+      # Normalizes a model reference to a separator- and case-insensitive key so
+      # "Base::FundHolding", "base/fund_holding" and "BaseFundHolding" all collapse
+      # to the same value ("basefundholding") for matching against real files.
+      def model_key(name)
+        name.to_s.gsub("::", "/").split("/").map { |segment| segment.tr("-", "_").delete("_").downcase }.join
+      end
+
+      def relative_model_path(file, models_dir)
+        file.sub("#{models_dir}/", "").sub(/\.rb$/, "")
+      end
+
+      # Canonical Ruby constant name for a resolved model file.
+      def model_class_name(model_file)
+        models_dir = File.join(active_project_path, "app", "models")
+        classify_model_name(relative_model_path(model_file, models_dir))
       end
 
       def classify_model_name(model_file)

data/lib/rails-mcp-server/analyzers/base_analyzer.rb

@@ -21,9 +21,12 @@ module RailsMcpServer
           f.write(script)
           f.flush
 
+          # No `2>/dev/null`: execute_rails_command captures stderr separately
+          # via Open3, keeps stdout (the JSON we parse) clean on success, and
+          # surfaces the real boot error on failure instead of a blank message.
           RailsMcpServer::RunProcess.execute_rails_command(
             active_project_path,
-            "bin/rails runner #{f.path} 2>/dev/null"
+            "bin/rails runner #{f.path}"
           )
         end
       end

data/lib/rails-mcp-server/tools/execute_ruby.rb

@@ -3,16 +3,30 @@ module RailsMcpServer
     tool_name "execute_ruby"
 
     description <<~DESC
-      Execute read-only Ruby code in the context of the Rails project. Use this for:
+      Execute Ruby code in the context of the Rails project, for inspection and
+      exploration. Use this for:
       - Complex queries that would require multiple tool calls
       - Filtering/transforming data before returning
       - Custom exploration of the codebase
 
+      This runs with the privileges of the rails-mcp-server process. The
+      restrictions below are best-effort guardrails against accidental writes
+      and obvious escapes, not a security boundary for untrusted code; only run
+      code you would run yourself.
+
       RESTRICTIONS:
       - Cannot create, modify, or delete files
       - Cannot read .env, credentials, key files, or .gitignore'd files
-      - Cannot access files outside the project directory
+      - Cannot access files outside the project directory (read-only system data
+        such as timezone files under /usr/share/zoneinfo is allowed)
       - Cannot execute shell commands or system calls
+      - Cannot `require` arbitrary libraries or `require_relative` project files.
+        Rails and the stdlib it loads (json, yaml, set, ...) are already
+        available under `bin/rails runner`; only a few pure-data libraries not
+        always preloaded (csv, and the timezone libs) may be required
+      - Database writes run inside a transaction that is always rolled back, so
+        treat this as read-only for data too (note: DDL may still commit on some
+        adapters, and after_commit callbacks do not fire)
 
       HELPER METHODS AVAILABLE:
       - read_file(path) - safely read a file
@@ -21,11 +35,17 @@ module RailsMcpServer
       - project_root - returns the project root path
 
       NOTE: Use `puts` to see output, e.g., puts read_file('Gemfile')
+
+      Some dual-use constructs (Kernel#open, send, public_send, const_get) are
+      not run immediately: the tool returns a CONFIRMATION REQUIRED message
+      explaining the risk. Re-invoke with confirm_risky: true only after the
+      user has reviewed the code and approved it.
     DESC
 
     arguments do
-      required(:code).filled(:string).description("Ruby code to execute (read-only operations only)")
+      required(:code).filled(:string).description("Ruby code to execute (inspection operations only)")
       optional(:timeout).filled(:integer).description("Timeout in seconds. Default: 30, Max: 60")
+      optional(:confirm_risky).filled(:bool).description("Set true ONLY after the user has explicitly approved running code that uses sandbox-bypass-capable constructs (send, public_send, const_get, Kernel#open). When false/absent, such code is not executed; the tool returns a CONFIRMATION REQUIRED message instead.")
     end
 
     # Patterns that indicate dangerous operations
@@ -51,6 +71,22 @@ module RailsMcpServer
       /Process\.(spawn|exec|fork)/i,
       /Shellwords/i,
 
+      # Pseudo-terminals and native/syscall bridges. PTY.spawn / PTY.getpty
+      # start a child process outside the Kernel#system guard; Fiddle and FFI
+      # can call libc (e.g. system(3), execve(2)) directly. None of these are
+      # needed for read-only inspection.
+      /\bPTY\b/,
+      /\bFiddle\b/,
+      /\bFFI\b/,
+
+      # Dynamic dispatch aimed at an execution/eval sink *by name* is hard
+      # blocked. The general send/public_send/const_get forms stay in the
+      # confirmation tier below; only a dangerous literal target is rejected
+      # outright, so `record.send(:name)` still works while
+      # `Process.send(:spawn, ...)` or `const_get("Open3")` do not.
+      /\b(?:public_send|__send__|send)\s*(?:\(\s*)?[:'"](?:system|exec|spawn|fork|eval|popen|syscall|`)/i,
+      /\bconst_get\s*(?:\(\s*)?['"](?:Open3|Process|PTY|Kernel|Socket|Fiddle|FFI|Binding|ObjectSpace|TCPSocket|UDPSocket)\b/i,
+
       # Network access
       /Net::(HTTP|FTP|SMTP)/i,
       /URI\.(open|parse)/i,
@@ -75,14 +111,50 @@ module RailsMcpServer
       /set_trace_func/i,
 
       # Environment/credentials access
-      /ENV\[/i,
-      /ENV\.fetch/i,
+      # Match any ENV usage (ENV[, ENV.fetch, ENV.to_h, ENV.values_at, ENV.each,
+      # ...). Case-sensitive so it doesn't flag `Rails.env` or a local `env`.
+      /\bENV\b/,
       /Rails\.application\.credentials/i,
       /Rails\.application\.secrets/i,
 
-      # Load/require that could execute arbitrary code
-      /load\s*[(\s]+[^)]*\$/i,
-      /require\s+[^'"]/i
+      # Load/require. Under `bin/rails runner` Rails, the app's models/gems, and
+      # the stdlib Rails loads on boot are already available, so inspection code
+      # almost never needs `require`. Dynamic requires and require_relative
+      # (loads/executes arbitrary project files) are refused outright; literal
+      # `require "lib"` is refused unless the lib is on REQUIRE_ALLOWLIST. This
+      # keeps dangerous stdlib escapes (`pty`, `open3`, `fiddle`, `ffi`,
+      # `socket`) out while still allowing the few pure-data libs that aren't
+      # always preloaded (e.g. csv, the timezone libs).
+      /\brequire_relative\b/i,
+      /require\s+[^'"]/i,
+      /load\s*[(\s]+[^)]*\$/i
+    ].freeze
+
+    # The only libraries a literal `require` may name. All are pure-Ruby, with
+    # no process/network/native-call surface: csv (not always preloaded) and
+    # the timezone libs Rails uses when code touches Time.zone. Everything else
+    # — notably any process/native bridge — is rejected. Matched
+    # case-insensitively; a trailing ".rb" is ignored.
+    REQUIRE_ALLOWLIST = %w[csv tzinfo date time].freeze
+
+    # Extracts a literal require target from `require "x"`, `require'x'`, or
+    # `require("x")`. Dynamic (non-literal) requires are already rejected by the
+    # /require\s+[^'"]/ pattern above.
+    REQUIRE_STATEMENT = /\brequire\b\s*(?:\(\s*)?(['"])([^'"]+)\1/
+
+    # Dual-use constructs that are NOT hard-blocked (they have legitimate
+    # read-only uses) but can defeat the static safety scan, so running them
+    # requires explicit user confirmation via confirm_risky: true.
+    # Each entry: [pattern, label, why-it-is-risky].
+    CONFIRMATION_REQUIRED_PATTERNS = [
+      [/(?<![.\w])open\s*\(/, "Kernel#open",
+        "`open(arg)` runs a shell command when arg begins with '|', and can open network/URI targets — both escape the sandbox."],
+      [/\bpublic_send\b/, "public_send",
+        "dynamic dispatch can invoke methods the static scan cannot see, e.g. reaching blocked system/file APIs indirectly."],
+      [/\bsend\s*[(\s]/, "send",
+        "dynamic dispatch can invoke methods the static scan cannot see, e.g. reaching blocked system/file APIs indirectly."],
+      [/\bconst_get\b/, "const_get",
+        "resolves constants by name at runtime, which can reach classes the static scan would otherwise block."]
     ].freeze
 
     # Sensitive file patterns (in addition to .gitignore)
@@ -104,6 +176,18 @@ module RailsMcpServer
       /id_ed25519/i
     ].freeze
 
+    # Read-only system data directories the sandbox may read. TZInfo lazily
+    # loads IANA timezone data on first Time.zone use; these are its default
+    # search paths plus /var/db/timezone, the real location behind macOS's
+    # /usr/share/zoneinfo symlink. Writes remain blocked by the File/Dir/
+    # FileUtils overrides.
+    ALLOWED_READ_PATHS = %w[
+      /usr/share/zoneinfo
+      /usr/share/lib/zoneinfo
+      /etc/zoneinfo
+      /var/db/timezone
+    ].freeze
+
     NO_OUTPUT_MESSAGE = <<~MSG
       Code executed successfully (no output).
 
@@ -113,7 +197,7 @@ module RailsMcpServer
         puts Dir.glob('app/models/*.rb')
     MSG
 
-    def call(code:, timeout: 30)
+    def call(code:, timeout: 30, confirm_risky: false)
       unless current_project
         return "No active project. Please switch to a project first."
       end
@@ -121,14 +205,20 @@ module RailsMcpServer
       timeout = [timeout.to_i, 60].min # Cap at 60 seconds
       timeout = 10 if timeout < 1
 
-      # Step 1: Static analysis - reject dangerous code
+      # Step 1: Static analysis - reject outright-dangerous code
       validation_error = validate_code_safety(code)
       return validation_error if validation_error
 
-      # Step 2: Build the sandboxed execution environment
+      # Step 2: Dual-use constructs require explicit user confirmation
+      unless confirm_risky
+        confirmation = confirmation_required(code)
+        return confirmation if confirmation
+      end
+
+      # Step 3: Build the sandboxed execution environment
       sandbox_code = build_sandbox(code)
 
-      # Step 3: Execute with timeout
+      # Step 4: Execute with timeout
       execute_sandboxed(sandbox_code, timeout)
     end
 
@@ -138,40 +228,121 @@ module RailsMcpServer
       FORBIDDEN_PATTERNS.each do |pattern|
         if code.match?(pattern)
           return "REJECTED: Code contains forbidden pattern (#{pattern.source.split("\\").first}...). " \
-                 "This tool only allows read-only operations."
+                 "This tool only allows a restricted set of inspection operations."
+        end
+      end
+
+      validate_requires(code)
+    end
+
+    # Rejects any literal `require` of a library outside REQUIRE_ALLOWLIST.
+    # (require_relative and dynamic requires are already rejected by the
+    # forbidden patterns.) Returns an error string, or nil when permitted.
+    def validate_requires(code)
+      code.scan(REQUIRE_STATEMENT).each do |_quote, lib|
+        normalized = lib.downcase.sub(/\.rb\z/, "")
+        unless REQUIRE_ALLOWLIST.include?(normalized)
+          return "REJECTED: require of '#{lib}' is not permitted. " \
+                 "Only these libraries may be required: #{REQUIRE_ALLOWLIST.join(", ")}."
         end
       end
       nil
     end
 
+    # Returns a message asking the model to confirm with the user when the code
+    # uses dual-use constructs, or nil when there is nothing to confirm.
+    def confirmation_required(code)
+      matched = CONFIRMATION_REQUIRED_PATTERNS.select { |pattern, _label, _reason| code.match?(pattern) }
+      return nil if matched.empty?
+
+      details = matched.map { |_pattern, label, reason| "  - `#{label}`: #{reason}" }.join("\n")
+
+      <<~MSG
+        CONFIRMATION REQUIRED: This code uses constructs that can bypass the sandbox's static safety checks:
+
+        #{details}
+
+        These are not blocked outright because they have legitimate read-only uses, but they can reach APIs the safety scan would otherwise stop. Ask the user to review the code and confirm they want to run it. If they approve, re-invoke execute_ruby with confirm_risky: true. Do not set confirm_risky yourself without the user's explicit approval.
+      MSG
+    end
+
     def build_sandbox(user_code)
       gitignore_patterns = parse_gitignore
       all_patterns = SENSITIVE_PATTERNS.map(&:source) + gitignore_patterns
       sensitive_patterns_ruby = all_patterns.map { |p| "Regexp.new(#{p.inspect}, Regexp::IGNORECASE)" }.join(",\n      ")
 
       <<~RUBY
+        require "stringio" # the File.open override below yields StringIO objects
+
         # Sandbox wrapper for safe execution
         module McpSandbox
-          PROJECT_ROOT = #{active_project_path.inspect}.freeze
+          # realpath-normalized so symlink resolution below compares against the
+          # canonical root (e.g. macOS /var -> /private/var) rather than a path
+          # that would never prefix-match a resolved target.
+          PROJECT_ROOT = File.realpath(#{active_project_path.inspect}).freeze
+
+          ALLOWED_READ_PATHS = #{ALLOWED_READ_PATHS.inspect}.freeze
+
+          # realpath-resolved forms of the allowlist, so a resolved target still
+          # matches when the allowed dir is itself a symlink (e.g. macOS
+          # /usr/share/zoneinfo -> /private/var/db/timezone/.../zoneinfo).
+          CANONICAL_ALLOWED_READ_PATHS = ALLOWED_READ_PATHS.map { |dir|
+            File.exist?(dir) ? File.realpath(dir) : dir
+          }.freeze
 
           SENSITIVE_PATTERNS = [
             #{sensitive_patterns_ruby}
           ].freeze
 
+          # Native method handles captured *before* the File/Dir overrides below
+          # replace them. Held in private constants so sandboxed user code has no
+          # public `File.original_read`-style alias to call the raw method back.
+          ORIGINAL_FILE_READ      = File.method(:read)
+          ORIGINAL_FILE_READLINES = File.method(:readlines)
+          ORIGINAL_FILE_BINREAD   = File.method(:binread)
+          ORIGINAL_FILE_EXIST     = File.method(:exist?)
+          ORIGINAL_FILE_DIRECTORY = File.method(:directory?)
+          ORIGINAL_FILE_FILE      = File.method(:file?)
+          ORIGINAL_FILE_REALPATH  = File.method(:realpath)
+          ORIGINAL_DIR_GLOB       = Dir.method(:glob)
+          ORIGINAL_DIR_ENTRIES    = Dir.method(:entries)
+          private_constant :ORIGINAL_FILE_READ, :ORIGINAL_FILE_READLINES,
+            :ORIGINAL_FILE_BINREAD, :ORIGINAL_FILE_EXIST, :ORIGINAL_FILE_DIRECTORY,
+            :ORIGINAL_FILE_FILE, :ORIGINAL_FILE_REALPATH, :ORIGINAL_DIR_GLOB,
+            :ORIGINAL_DIR_ENTRIES
+
           class PathViolation < StandardError; end
           class SensitiveFileViolation < StandardError; end
           class WriteViolation < StandardError; end
 
           module_function
 
+          # Resolve symlinks so a link *inside* the project cannot be used to
+          # read a target outside it. realpath needs the path to exist, so for a
+          # not-yet-existing path resolve the deepest existing ancestor and
+          # re-append the remainder (which still catches a symlinked ancestor).
+          def resolve_symlinks(expanded)
+            return ORIGINAL_FILE_REALPATH.call(expanded) if ORIGINAL_FILE_EXIST.call(expanded)
+
+            parent = File.dirname(expanded)
+            return expanded if parent == expanded
+
+            File.join(resolve_symlinks(parent), File.basename(expanded))
+          end
+
           def validate_path!(path)
             expanded = File.expand_path(path, PROJECT_ROOT)
+            resolved = resolve_symlinks(expanded)
+
+            if (ALLOWED_READ_PATHS + CANONICAL_ALLOWED_READ_PATHS).any? { |dir| resolved == dir || resolved.start_with?(dir + "/") }
+              return resolved
+            end
 
-            unless expanded.start_with?(PROJECT_ROOT + "/") || expanded == PROJECT_ROOT
+            unless resolved.start_with?(PROJECT_ROOT + "/") || resolved == PROJECT_ROOT
               raise PathViolation, "Access denied: path '\#{path}' is outside project directory"
             end
 
-            relative_path = expanded.sub(PROJECT_ROOT + "/", "")
+            relative_path = resolved.sub(PROJECT_ROOT + "/", "")
 
             SENSITIVE_PATTERNS.each do |pattern|
               if relative_path.match?(pattern)
@@ -179,37 +350,48 @@ module RailsMcpServer
               end
             end
 
-            expanded
+            resolved
           end
 
           def safe_read(path)
-            validated_path = validate_path!(path)
-            File.original_read(validated_path)
+            ORIGINAL_FILE_READ.call(validate_path!(path))
+          end
+
+          def safe_readlines(path)
+            ORIGINAL_FILE_READLINES.call(validate_path!(path))
+          end
+
+          def safe_binread(path)
+            ORIGINAL_FILE_BINREAD.call(validate_path!(path))
+          end
+
+          def safe_foreach(path, &block)
+            lines = safe_readlines(path)
+            return lines.each unless block
+
+            lines.each(&block)
           end
 
           def safe_exist?(path)
-            validated_path = validate_path!(path)
-            File.original_exist?(validated_path)
+            ORIGINAL_FILE_EXIST.call(validate_path!(path))
           rescue PathViolation, SensitiveFileViolation
             false
           end
 
           def safe_directory?(path)
-            validated_path = validate_path!(path)
-            File.original_directory?(validated_path)
+            ORIGINAL_FILE_DIRECTORY.call(validate_path!(path))
           rescue PathViolation, SensitiveFileViolation
             false
           end
 
           def safe_file?(path)
-            validated_path = validate_path!(path)
-            File.original_file?(validated_path)
+            ORIGINAL_FILE_FILE.call(validate_path!(path))
           rescue PathViolation, SensitiveFileViolation
             false
           end
 
           def safe_glob(pattern, base: PROJECT_ROOT)
-            Dir.original_glob(File.join(base, pattern)).select do |path|
+            ORIGINAL_DIR_GLOB.call(File.join(base, pattern)).select do |path|
               validate_path!(path)
               true
             rescue PathViolation, SensitiveFileViolation
@@ -218,23 +400,58 @@ module RailsMcpServer
           end
 
           def safe_entries(path)
-            validated_path = validate_path!(path)
-            Dir.original_entries(validated_path).reject { |e| e.start_with?(".") }
+            ORIGINAL_DIR_ENTRIES.call(validate_path!(path)).reject { |e| e.start_with?(".") }
+          end
+
+          # True only when ActiveRecord is loaded *and* a connection can be
+          # obtained, so we never turn a pure-Ruby read-only snippet into a
+          # database connection error just to wrap it in a transaction.
+          def database_available?
+            return false unless defined?(ActiveRecord::Base)
+
+            ActiveRecord::Base.connection
+            true
+          rescue StandardError
+            false
+          end
+
+          # Run the block inside a transaction that is *always* rolled back, so
+          # accidental writes are undone. Harm reduction, not a guarantee: DDL
+          # auto-commits on some adapters (e.g. MySQL) and after_commit
+          # callbacks are suppressed. Falls back to a plain call when no
+          # database is available. Real exceptions still propagate (and also
+          # trigger the rollback).
+          def readonly_guard
+            return yield unless database_available?
+
+            result = nil
+            ActiveRecord::Base.transaction do
+              result = yield
+              raise ActiveRecord::Rollback
+            end
+            result
           end
         end
 
         # Override File class methods
         class File
           class << self
-            alias_method :original_read, :read
-            alias_method :original_exist?, :exist?
-            alias_method :original_directory?, :directory?
-            alias_method :original_file?, :file?
-
             def read(path, *args)
               McpSandbox.safe_read(path)
             end
 
+            def readlines(path, *args)
+              McpSandbox.safe_readlines(path)
+            end
+
+            def binread(path, *args)
+              McpSandbox.safe_binread(path)
+            end
+
+            def foreach(path, *args, &block)
+              McpSandbox.safe_foreach(path, &block)
+            end
+
             def exist?(path)
               McpSandbox.safe_exist?(path)
             end
@@ -272,9 +489,6 @@ module RailsMcpServer
         # Override Dir class methods
         class Dir
           class << self
-            alias_method :original_glob, :glob
-            alias_method :original_entries, :entries
-
             def glob(pattern, *args)
               McpSandbox.safe_glob(pattern)
             end
@@ -291,6 +505,29 @@ module RailsMcpServer
           end
         end
 
+        # Override IO read entry points. File < IO, but IO.read / IO.readlines /
+        # IO.binread / IO.foreach are separate class methods that bypass the File
+        # overrides above, so they must be sandboxed independently.
+        class IO
+          class << self
+            def read(path, *args)
+              McpSandbox.safe_read(path)
+            end
+
+            def readlines(path, *args)
+              McpSandbox.safe_readlines(path)
+            end
+
+            def binread(path, *args)
+              McpSandbox.safe_binread(path)
+            end
+
+            def foreach(path, *args, &block)
+              McpSandbox.safe_foreach(path, &block)
+            end
+          end
+        end
+
         # Block FileUtils entirely
         if defined?(FileUtils)
           module FileUtils
@@ -346,8 +583,13 @@ module RailsMcpServer
         end
 
         # ============ USER CODE BELOW ============
+        # Wrapped in an always-rolled-back transaction so accidental DB writes
+        # (delete_all, update, save, raw DML) are undone. See McpSandbox
+        # .readonly_guard for the caveats; it's a no-op without a database.
         begin
-          #{user_code}
+          McpSandbox.readonly_guard do
+            #{user_code}
+          end
         rescue McpSandbox::PathViolation => e
           puts "PATH ERROR: \#{e.message}"
         rescue McpSandbox::SensitiveFileViolation => e
@@ -386,23 +628,19 @@ module RailsMcpServer
 
     def execute_sandboxed(code, timeout)
       require "tempfile"
-      require "timeout"
 
       Tempfile.create(["mcp_sandbox", ".rb"]) do |f|
         f.write(code)
         f.flush
 
-        begin
-          Timeout.timeout(timeout) do
-            result = RailsMcpServer::RunProcess.execute_rails_command(
-              active_project_path,
-              "bin/rails runner #{f.path} 2>&1"
-            )
-            result.empty? ? NO_OUTPUT_MESSAGE : result
-          end
-        rescue Timeout::Error
-          "TIMEOUT: Execution exceeded #{timeout} seconds"
-        end
+        # RunProcess enforces the timeout by killing the whole process group, so
+        # a runaway `rails runner` is actually terminated rather than orphaned.
+        result = RailsMcpServer::RunProcess.execute_rails_command(
+          active_project_path,
+          "bin/rails runner #{f.path} 2>&1",
+          timeout: timeout
+        )
+        result.to_s.empty? ? NO_OUTPUT_MESSAGE : result
       end
     end
   end

data/lib/rails-mcp-server/utilities/run_process.rb

@@ -1,26 +1,42 @@
 require "bundler"
 require "shellwords"
+require "open3"
+require "timeout"
 
 module RailsMcpServer
   class RunProcess
-    def self.execute_rails_command(project_path, command)
+    # `timeout` (seconds) bounds execution. When set, the command runs in its
+    # own process group so a timeout kills the whole tree; nil keeps the
+    # original unbounded behavior.
+    def self.execute_rails_command(project_path, command, timeout: nil)
       RailsMcpServer.log(:debug, "Executing: #{command}")
 
       Bundler.with_unbundled_env do
         subprocess_env = ENV.to_h
         subprocess_env.delete("BUNDLE_GEMFILE")
 
-        # Set RBENV_VERSION from project's .ruby-version if it exists
-        ruby_version_file = File.join(project_path, ".ruby-version")
-        if File.exist?(ruby_version_file)
-          subprocess_env["RBENV_VERSION"] = File.read(ruby_version_file).strip
-        else
-          subprocess_env.delete("RBENV_VERSION")
-        end
+        # Make `bin/rails` resolve the *project's* Ruby regardless of which
+        # version manager is in use. mise, asdf and rbenv each expose a "shims"
+        # directory whose wrappers pick the Ruby from the project's
+        # .ruby-version / .tool-versions / .mise.toml at run time. Prepending it
+        # to PATH is manager-agnostic and needs no manager-specific environment
+        # variables (the previous RBENV_VERSION handling only worked for rbenv).
+        prepend_version_manager_shims(subprocess_env)
 
         shell = ENV.fetch("SHELL", "/bin/bash")
-        shell_command = "cd #{Shellwords.escape(project_path)} && #{command}"
-        stdout_str, stderr_str, status = Open3.capture3(subprocess_env, shell, "-l", "-c", shell_command)
+        shell_command = build_shell_command(project_path, command)
+
+        # A *non-login* shell (`-c`, not `-l`). A login shell triggers macOS
+        # `path_helper` (via /etc/zprofile), which rebuilds PATH with /usr/bin
+        # ahead of the manager's shims — the exact reason the system Ruby leaked
+        # in. It also never sources ~/.zshrc, where mise/asdf activation usually
+        # lives. `-c` keeps the PATH we assembled above intact.
+        stdout_str, stderr_str, status =
+          if timeout
+            capture3_with_timeout(subprocess_env, shell, shell_command, timeout)
+          else
+            Open3.capture3(subprocess_env, shell, "-c", shell_command)
+          end
 
         if status.success?
           RailsMcpServer.log(:debug, "Command succeeded")
@@ -33,9 +49,85 @@ module RailsMcpServer
           "Error executing Rails command: #{command}\n\n#{error_output}"
         end
       end
+    rescue Timeout::Error
+      RailsMcpServer.log(:error, "Command timed out after #{timeout} seconds")
+      "TIMEOUT: Execution exceeded #{timeout} seconds"
     rescue => e
       RailsMcpServer.log(:error, "Exception executing Rails command: #{e.message}")
       "Exception executing command: #{e.message}"
     end
+
+    # Run the command in its own process group so a timeout can kill the entire
+    # tree (the shell *and* its `rails runner` grandchild). Open3.capture3 gives
+    # no handle to signal the group, so drive popen3 directly and drain stdout/
+    # stderr on separate threads to avoid a full-pipe deadlock. Re-raises
+    # Timeout::Error after killing; the caller maps it to a user-facing message.
+    def self.capture3_with_timeout(env, shell, shell_command, timeout)
+      Open3.popen3(env, shell, "-c", shell_command, pgroup: true) do |stdin, stdout, stderr, wait_thr|
+        stdin.close
+        out = +""
+        err = +""
+        out_reader = Thread.new { out << stdout.read }
+        err_reader = Thread.new { err << stderr.read }
+
+        begin
+          status = Timeout.timeout(timeout) { wait_thr.value }
+          out_reader.join
+          err_reader.join
+          [out, err, status]
+        rescue Timeout::Error
+          kill_process_group(wait_thr.pid)
+          out_reader.join(1)
+          err_reader.join(1)
+          raise
+        end
+      end
+    end
+
+    # KILL the process group led by `pid`. Negative pid targets the whole group.
+    def self.kill_process_group(pid)
+      Process.kill("KILL", -Process.getpgid(pid))
+    rescue Errno::ESRCH, Errno::EPERM
+      # Already exited or not signalable; nothing to clean up.
+    end
+
+    # Shim directories for the version managers installed on this machine,
+    # detected by their well-known locations so resolution works even in a
+    # non-login shell that never sourced the manager's activation. Honors the
+    # managers' own overrides (MISE_DATA_DIR / XDG_DATA_HOME, ASDF_DATA_DIR,
+    # RBENV_ROOT). A machine normally has just one.
+    def self.version_manager_shim_dirs(home: Dir.home, env: ENV)
+      mise_data = env["MISE_DATA_DIR"] ||
+        File.join(env["XDG_DATA_HOME"] || File.join(home, ".local", "share"), "mise")
+
+      [
+        File.join(mise_data, "shims"),                                        # mise
+        File.join(env["ASDF_DATA_DIR"] || File.join(home, ".asdf"), "shims"), # asdf
+        File.join(env["RBENV_ROOT"] || File.join(home, ".rbenv"), "shims")    # rbenv
+      ].select { |dir| File.directory?(dir) }
+    end
+
+    # Prepend the detected shim directories to the subprocess PATH.
+    def self.prepend_version_manager_shims(env)
+      dirs = version_manager_shim_dirs(env: env)
+      return if dirs.empty?
+
+      path = env["PATH"].to_s
+      env["PATH"] = (path.empty? ? dirs : dirs + [path]).join(File::PATH_SEPARATOR)
+    end
+
+    # rvm has no shims — it activates through a shell function keyed off the
+    # working directory, so source it (before `cd`, so its chpwd hook is in
+    # place) when it is installed. Everything else just runs in the project dir.
+    def self.build_shell_command(project_path, command)
+      cd = "cd #{Shellwords.escape(project_path)}"
+      rvm_script = File.join(Dir.home, ".rvm", "scripts", "rvm")
+
+      if File.exist?(rvm_script)
+        "source #{Shellwords.escape(rvm_script)} && #{cd} && #{command}"
+      else
+        "#{cd} && #{command}"
+      end
+    end
   end
 end

data/lib/rails-mcp-server/version.rb

@@ -1,3 +1,3 @@
 module RailsMcpServer
-  VERSION = "1.5.1"
+  VERSION = "1.6.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-mcp-server
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.1
 platform: ruby
 authors:
 - Mario Alberto Chávez Cárdenas
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -127,14 +127,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.25'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.25'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: minitest-reporters
   requirement: !ruby/object:Gem::Requirement
@@ -155,14 +155,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '3.0'
 description: A Ruby implementation of Model Context Protocol server for Rails projects
 email:
 - mario.chavez@gmail.com
@@ -180,6 +180,7 @@ files:
 - config/resources.yml
 - docs/AGENT.md
 - docs/COPILOT_AGENT.md
+- docs/GOVERNED_CLIENTS.md
 - docs/RESOURCES.md
 - exe/rails-mcp-config
 - exe/rails-mcp-server
@@ -241,14 +242,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.17
 specification_version: 4
 summary: MCP server for Rails projects
 test_files: []