little_ghost 0.3.0 → 0.5.0

data/lib/little_ghost/session_stores/agent_core_memory.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "json"
 require "securerandom"
+require_relative "../data_map"
 require_relative "../session_store"
 
 module LittleGhost
@@ -49,10 +50,15 @@ module LittleGhost
     # but horizontally scaled applications need an external lock or unique
     # active-run record. Commits use generation and checkpoint records so an
     # incomplete write is never exposed as a successful snapshot.
+    #
+    # AgentCore checkpoints are versioned. This store reads supported historical
+    # versions without writing during #load, then writes the current checkpoint
+    # format when the session next appends or replaces its snapshot.
     class AgentCoreMemory < SessionStore
       MESSAGE_PREFIX = "little_ghost:message:v4:" # :nodoc:
       MESSAGE_CHUNK_PREFIX = "little_ghost:message_chunk:v4:" # :nodoc:
-      CHECKPOINT_PREFIX = "little_ghost:checkpoint:v4:" # :nodoc:
+      CHECKPOINT_PREFIX = "little_ghost:checkpoint:v5:" # :nodoc:
+      LEGACY_CHECKPOINT_PREFIX = "little_ghost:checkpoint:v4:" # :nodoc:
       CONVERSATIONAL_TEXT_LIMIT = 100_000 # :nodoc:
       MESSAGE_CHUNK_CONTENT_LIMIT = 90_000 # :nodoc:
       EVENT_PAYLOAD_LIMIT = 100 # :nodoc:
@@ -63,7 +69,8 @@ module LittleGhost
       SYMBOL_KEY_PREFIX = "little_ghost:symbol:" # :nodoc:
       STRING_KEY_PREFIX = "little_ghost:string:" # :nodoc:
       MESSAGE_EVENT_TYPE = "message_v4" # :nodoc:
-      CHECKPOINT_EVENT_TYPE = "checkpoint_v4" # :nodoc:
+      CHECKPOINT_EVENT_TYPE = "checkpoint_v5" # :nodoc:
+      LEGACY_CHECKPOINT_EVENT_TYPE = "checkpoint_v4" # :nodoc:
       CONVERSATION_PROJECTION_EVENT_TYPE = "conversation_projection_v1" # :nodoc:
       PROJECTION_METADATA_KEYS = %w[
         little_ghost_parent_link
@@ -135,27 +142,39 @@ module LittleGhost
       # +expected_count+ matches the latest remote generation.
       def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         actor = self.class.safe_id(required_actor_id(actor_id))
         session = self.class.safe_id(id)
         key = [actor, session]
         synchronize_persistence(key) do
-          head, = latest_checkpoint(actor, session)
+          head, lineage = latest_checkpoint(actor, session)
           persistence = head&.fetch(:checkpoint)
           persisted_count = persistence&.fetch(:message_count, 0) || 0
           unless persisted_count == expected_count
             raise ProtocolError, "Session changed while it was being updated"
           end
 
-          generation = persistence&.fetch(:generation) || SecureRandom.uuid
+          if head && head.fetch(:format) != CHECKPOINT_EVENT_TYPE
+            existing = messages_from(message_records_for(actor, session, lineage:), lineage:)
+            messages = [*existing, *messages].freeze
+            expected_count = 0
+            persistence = head.fetch(:checkpoint)
+            root = true
+            generation = SecureRandom.uuid
+          else
+            root = persistence.nil?
+            generation = persistence&.fetch(:generation) || SecureRandom.uuid
+          end
           commit_id = SecureRandom.uuid
           plan = plan_messages(messages, generation:, commit_id:, offset: expected_count)
           checkpoint = build_checkpoint(
             persistence:,
             generation:,
             commit_id:,
-            root: persistence.nil?,
+            root:,
             plan:,
-            message_count: expected_count + messages.length,
+            message_count: root ? messages.length : expected_count + messages.length,
             state:,
             metadata:
           )
@@ -167,6 +186,8 @@ module LittleGhost
       # Replaces the visible snapshot by committing a new remote generation.
       def replace(id, messages:, state:, metadata:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         actor = self.class.safe_id(required_actor_id(actor_id))
         session = self.class.safe_id(id)
         key = [actor, session]
@@ -379,27 +400,29 @@ module LittleGhost
 
       def checkpoint_entries(actor_id, session_id)
         entries = []
-        each_event(
-          actor_id,
-          session_id,
-          filter: metadata_filter(type: CHECKPOINT_EVENT_TYPE),
-          event_limit: MAX_CHECKPOINT_EVENTS,
-          payload_limit: MAX_CHECKPOINT_EVENTS,
-          byte_limit: MAX_CHECKPOINT_READ_BYTES
-        ) do |event|
-          data = event_session_data(event)
-          raise ProtocolError, "AgentCore session checkpoint event is invalid" unless data
-          unless event.event_timestamp.is_a?(Time)
-            raise ProtocolError, "AgentCore session checkpoint timestamp is invalid"
-          end
+        [LEGACY_CHECKPOINT_EVENT_TYPE, CHECKPOINT_EVENT_TYPE].each do |format|
+          each_event(
+            actor_id,
+            session_id,
+            filter: metadata_filter(type: format),
+            event_limit: MAX_CHECKPOINT_EVENTS,
+            payload_limit: MAX_CHECKPOINT_EVENTS,
+            byte_limit: MAX_CHECKPOINT_READ_BYTES
+          ) do |event|
+            data = event_session_data(event, format:)
+            raise ProtocolError, "AgentCore session checkpoint event is invalid" unless data
+            unless event.event_timestamp.is_a?(Time)
+              raise ProtocolError, "AgentCore session checkpoint timestamp is invalid"
+            end
 
-          checkpoint = normalize_checkpoint(data)
-          unless event_metadata_value(event, GENERATION_METADATA_KEY) == checkpoint.fetch(:generation) &&
-              event_metadata_value(event, COMMIT_METADATA_KEY) == checkpoint.fetch(:commit_id)
-            raise ProtocolError, "AgentCore session checkpoint metadata is invalid"
-          end
+            checkpoint = normalize_checkpoint(data, format:)
+            unless event_metadata_value(event, GENERATION_METADATA_KEY) == checkpoint.fetch(:generation) &&
+                event_metadata_value(event, COMMIT_METADATA_KEY) == checkpoint.fetch(:commit_id)
+              raise ProtocolError, "AgentCore session checkpoint metadata is invalid"
+            end
 
-          entries << {checkpoint:, event_timestamp: event.event_timestamp}.freeze
+            entries << {checkpoint:, event_timestamp: event.event_timestamp, format:}.freeze
+          end
         end
         entries
       end
@@ -666,12 +689,13 @@ module LittleGhost
         expected.length.times.map { |sequence| indexed.fetch(sequence) }
       end
 
-      def event_session_data(event)
+      def event_session_data(event, format:)
+        prefix = (format == LEGACY_CHECKPOINT_EVENT_TYPE) ? LEGACY_CHECKPOINT_PREFIX : CHECKPOINT_PREFIX
         values = event_payloads(event).filter_map do |payload|
           blob = payload.respond_to?(:blob) ? payload.blob : nil
-          next unless blob.is_a?(String) && blob.start_with?(CHECKPOINT_PREFIX)
+          next unless blob.is_a?(String) && blob.start_with?(prefix)
 
-          checkpoint = deserialize_checkpoint(blob.delete_prefix(CHECKPOINT_PREFIX))
+          checkpoint = deserialize_checkpoint(blob.delete_prefix(prefix), format:)
           checkpoint if checkpoint.is_a?(Hash)
         end
         values.one? ? values.first : nil
@@ -854,37 +878,21 @@ module LittleGhost
       end
 
       def serialize_checkpoint(checkpoint)
-        document = checkpoint.merge(
-          "state" => encode_hash_keys(checkpoint.fetch("state")),
-          "metadata" => encode_hash_keys(checkpoint.fetch("metadata"))
-        )
-        JSON.generate(document)
+        JSON.generate(checkpoint)
       end
 
-      def deserialize_checkpoint(value)
+      def deserialize_checkpoint(value, format: CHECKPOINT_EVENT_TYPE)
         document = JSON.parse(value)
         return document unless document.is_a?(Hash)
 
-        document["state"] = decode_hash_keys(document.fetch("state", {}))
-        document["metadata"] = decode_hash_keys(document.fetch("metadata", {}))
-        document
-      end
-
-      def encode_hash_keys(value)
-        case value
-        when Hash
-          value.to_h do |key, child|
-            prefix = key.is_a?(Symbol) ? SYMBOL_KEY_PREFIX : STRING_KEY_PREFIX
-            ["#{prefix}#{key}", encode_hash_keys(child)]
-          end
-        when Array
-          value.map { |child| encode_hash_keys(child) }
-        else
-          value
+        if format == LEGACY_CHECKPOINT_EVENT_TYPE
+          document["state"] = decode_legacy_hash_keys(document.fetch("state", {}))
+          document["metadata"] = decode_legacy_hash_keys(document.fetch("metadata", {}))
         end
+        document
       end
 
-      def decode_hash_keys(value)
+      def decode_legacy_hash_keys(value)
         case value
         when Hash
           value.to_h do |key, child|
@@ -893,10 +901,10 @@ module LittleGhost
             else
               key.delete_prefix(STRING_KEY_PREFIX)
             end
-            [decoded_key, decode_hash_keys(child)]
+            [decoded_key, decode_legacy_hash_keys(child)]
           end
         when Array
-          value.map { |child| decode_hash_keys(child) }
+          value.map { |child| decode_legacy_hash_keys(child) }
         else
           value
         end
@@ -984,7 +992,7 @@ module LittleGhost
         end
       end
 
-      def normalize_checkpoint(value)
+      def normalize_checkpoint(value, format: CHECKPOINT_EVENT_TYPE)
         if serialize_checkpoint(value.transform_keys(&:to_s)).bytesize > MAX_CHECKPOINT_SERIALIZED_BYTES
           raise ProtocolError, "AgentCore session checkpoint exceeds the byte limit"
         end
@@ -1002,8 +1010,8 @@ module LittleGhost
         serialized_bytes = data.fetch("serialized_bytes")
         event_count = data.fetch("event_count")
         payload_count = data.fetch("payload_count")
-        state = data.fetch("state", {})
-        metadata = data.fetch("metadata", {})
+        state = DataMap.new(data.fetch("state", {})).to_h
+        metadata = DataMap.new(data.fetch("metadata", {})).to_h
         valid = valid_identifier?(generation) && valid_identifier?(commit_id) &&
           (parent_commit_id.nil? || valid_identifier?(parent_commit_id)) &&
           generation_revision.is_a?(Integer) && generation_revision.between?(1, MAX_REVISION) &&

data/lib/little_ghost/session_stores/filesystem.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "securerandom"
+require_relative "../data_map"
+require_relative "../session_store"
+
+module LittleGhost
+  module SessionStores
+    # Filesystem preserves LittleGhost sessions across process restarts in an
+    # application-controlled directory. Use it for durable local development,
+    # a single-host service, or processes that share a suitable filesystem.
+    #
+    #   store = LittleGhost::SessionStores::Filesystem.new(
+    #     root: "/var/lib/customer_support/sessions"
+    #   )
+    #
+    # Configure the resulting store through Configuration#session_store, or
+    # pass it directly when opening a Session. Calls for the same session wait
+    # for one writer, including when separate Ruby processes share the root.
+    #
+    # **Warning:** The root contains readable session data and is not encrypted.
+    # Its complete path must be application-controlled: anyone able to read it
+    # can read session data, and anyone able to replace it can alter sessions.
+    #
+    # Session data is stored as ordinary JSON with canonical String keys. A
+    # value outside that boundary raises ProtocolError without replacing the
+    # previous snapshot. Shared roots require filesystem support for file
+    # locking and atomic rename.
+    class Filesystem < SessionStore
+      FORMAT_VERSION = 1 # :nodoc:
+
+      # Creates a store rooted at +root+ and creates the directory when needed.
+      #
+      # +root+ must be a private, non-symlinked directory. The application owns
+      # the complete path and must not let an untrusted request choose it.
+      # Raises ArgumentError when the root does not meet those requirements.
+      def initialize(root:)
+        super()
+        @root = File.expand_path(String(root))
+        raise ArgumentError, "root must not be empty" if root.to_s.empty?
+
+        FileUtils.mkdir_p(@root, mode: 0o700)
+        validate_root!
+      end
+
+      # Returns the stored snapshot for +id+, or +nil+ before the first write.
+      #
+      # +actor_id+ must match the actor that created an existing session.
+      # Raises Error for an actor mismatch and ProtocolError for an invalid or
+      # unsafe persisted snapshot.
+      def load(id, actor_id: nil)
+        with_lock(id) do
+          snapshot = read_snapshot(id)
+          validate_actor!(snapshot, actor_id) if snapshot
+          snapshot
+        end
+      end
+
+      # Atomically appends sanitized +messages+ and returns the updated snapshot.
+      #
+      # +expected_count+ must match the stored history length. +state+ and
+      # +metadata+ must meet this store's JSON boundary. Raises ProtocolError
+      # when another writer changed the session or the snapshot cannot be read
+      # or written. Raises Error when +actor_id+ does not match the session.
+      def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
+        messages = persistable_messages(messages)
+        state = canonical_map(state)
+        metadata = canonical_map(metadata)
+        with_lock(id) do
+          current = read_snapshot(id)
+          validate_actor!(current, actor_id) if current
+          current ||= empty_snapshot(actor_id)
+          unless current.fetch(:messages).length == expected_count
+            raise ProtocolError, "Session changed while it was being updated"
+          end
+
+          snapshot = {
+            actor_digest: current.fetch(:actor_digest),
+            messages: [*current.fetch(:messages), *messages].freeze,
+            state:,
+            metadata:
+          }.freeze
+          write_snapshot(id, snapshot)
+          public_snapshot(snapshot)
+        end
+      end
+
+      # Atomically replaces the complete persisted snapshot and returns it.
+      #
+      # +state+, +metadata+, and +actor_id+ follow the same requirements as
+      # #append.
+      def replace(id, messages:, state:, metadata:, actor_id: nil)
+        messages = persistable_messages(messages)
+        state = canonical_map(state)
+        metadata = canonical_map(metadata)
+        with_lock(id) do
+          current = read_snapshot(id)
+          validate_actor!(current, actor_id) if current
+          snapshot = {
+            actor_digest: current ? current.fetch(:actor_digest) : actor_digest(actor_id),
+            messages: messages.freeze,
+            state:,
+            metadata:
+          }.freeze
+          write_snapshot(id, snapshot)
+          public_snapshot(snapshot)
+        end
+      end
+
+      private
+
+      def empty_snapshot(actor_id)
+        {
+          actor_digest: actor_digest(actor_id),
+          messages: [].freeze,
+          state: {}.freeze,
+          metadata: {}.freeze
+        }.freeze
+      end
+
+      def public_snapshot(snapshot)
+        snapshot.slice(:messages, :state, :metadata)
+      end
+
+      def validate_actor!(snapshot, actor_id)
+        return if snapshot.fetch(:actor_digest) == actor_digest(actor_id)
+
+        raise Error, "Session actor does not match"
+      end
+
+      def with_lock(id)
+        path = lock_path(id)
+        validate_entry!(path) if File.exist?(path) || File.symlink?(path)
+        File.open(path, File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          yield
+        ensure
+          lock.flock(File::LOCK_UN)
+        end
+      end
+
+      def read_snapshot(id)
+        path = snapshot_path(id)
+        return unless File.exist?(path) || File.symlink?(path)
+
+        validate_entry!(path)
+
+        document = JSON.parse(File.binread(path))
+        validate_document!(document)
+        snapshot = document.fetch("snapshot")
+        validate_snapshot!(snapshot)
+        {
+          actor_digest: document.fetch("actor_digest"),
+          messages: Array(snapshot.fetch("messages")).map { |message| Message.coerce(message) }.freeze,
+          state: snapshot.fetch("state"),
+          metadata: snapshot.fetch("metadata")
+        }.freeze
+      rescue JSON::ParserError, KeyError, TypeError, ArgumentError, NoMethodError => error
+        raise ProtocolError, "Filesystem session snapshot is invalid: #{error.class}"
+      end
+
+      def write_snapshot(id, snapshot)
+        serialized_snapshot = public_snapshot(snapshot).merge(
+          messages: snapshot.fetch(:messages).map(&:to_h)
+        )
+        document = {
+          "version" => FORMAT_VERSION,
+          "actor_digest" => snapshot.fetch(:actor_digest),
+          "snapshot" => serialized_snapshot
+        }
+        document["digest"] = Digest::SHA256.hexdigest(JSON.generate(document))
+        write_atomically(snapshot_path(id), JSON.generate(document))
+      rescue JSON::GeneratorError, TypeError => error
+        raise ProtocolError, "Filesystem session snapshot could not be serialized: #{error.class}"
+      end
+
+      def validate_document!(document)
+        raise ArgumentError unless document.is_a?(Hash)
+        raise ArgumentError unless document.fetch("version") == FORMAT_VERSION
+        raise ArgumentError unless document.fetch("actor_digest").match?(/\A[0-9a-f]{64}\z/)
+        digest = document.fetch("digest")
+        raise ArgumentError unless digest.is_a?(String) && digest.match?(/\A[0-9a-f]{64}\z/)
+
+        expected = document.except("digest")
+        raise ArgumentError unless Digest::SHA256.hexdigest(JSON.generate(expected)) == digest
+      end
+
+      def validate_snapshot!(snapshot)
+        raise ArgumentError unless snapshot.is_a?(Hash)
+        raise ArgumentError unless snapshot.fetch("messages").is_a?(Array)
+        DataMap.new(snapshot.fetch("state"))
+        DataMap.new(snapshot.fetch("metadata"))
+      end
+
+      def canonical_map(value)
+        DataMap.new(value).to_h
+      rescue ArgumentError => error
+        raise ProtocolError, "Filesystem session data is invalid: #{error.message}"
+      end
+
+      def write_atomically(path, content)
+        validate_entry!(path) if File.exist?(path) || File.symlink?(path)
+        temporary = "#{path}.#{Process.pid}.#{SecureRandom.hex(8)}.tmp"
+        File.open(temporary, "wb", 0o600) do |file|
+          file.write(content)
+          file.flush
+          file.fsync
+        end
+        File.rename(temporary, path)
+        sync_root
+      ensure
+        File.delete(temporary) if temporary && File.exist?(temporary)
+      end
+
+      def sync_root
+        File.open(@root, File::RDONLY) { |directory| directory.fsync }
+      rescue SystemCallError
+        nil
+      end
+
+      def validate_root!
+        stat = File.lstat(@root)
+        unless stat.directory? && !stat.symlink? && private_mode?(stat)
+          raise ArgumentError, "root must be a private, non-symlinked directory"
+        end
+      end
+
+      def validate_entry!(path)
+        stat = File.lstat(path)
+        unless stat.file? && !stat.symlink? && private_mode?(stat)
+          raise ProtocolError, "Filesystem session entry is unsafe"
+        end
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def private_mode?(stat)
+        (stat.mode & 0o077).zero?
+      end
+
+      def snapshot_path(id)
+        File.join(@root, "#{session_digest(id)}.json")
+      end
+
+      def lock_path(id)
+        File.join(@root, "#{session_digest(id)}.lock")
+      end
+
+      def session_digest(id)
+        Digest::SHA256.hexdigest("little_ghost/filesystem_session/v1\0#{String(id)}")
+      end
+
+      def actor_digest(actor_id)
+        Digest::SHA256.hexdigest(JSON.generate([actor_id.nil?, actor_id&.to_s]))
+      end
+    end
+  end
+end

data/lib/little_ghost/session_stores/memory.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "../data_map"
+require_relative "../session_store"
+
 module LittleGhost
   # Ready-to-use persistence implementations for LittleGhost conversations.
   module SessionStores
@@ -32,6 +35,8 @@ module LittleGhost
       # stored conversation, then returns the updated snapshot.
       def append(id, messages:, state:, metadata:, expected_count:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         @records_mutex.synchronize do
           key = id.to_s
           record = @records[key]
@@ -56,6 +61,8 @@ module LittleGhost
       # Replaces the complete in-memory snapshot with sanitized +messages+.
       def replace(id, messages:, state:, metadata:, actor_id: nil)
         messages = persistable_messages(messages)
+        state = DataMap.new(state).to_h
+        metadata = DataMap.new(metadata).to_h
         @records_mutex.synchronize do
           key = id.to_s
           validate_actor!(@records[key], actor_id)

data/lib/little_ghost/skills/catalog.rb

@@ -2,7 +2,7 @@
 
 require "yaml"
 require "erb"
-require "pathname"
+require_relative "resource_root"
 
 module LittleGhost
   module Skills
@@ -20,12 +20,16 @@ module LittleGhost
     # YAML are rejected or skipped before instructions reach a model. Optional
     # resource listings are limited by count and depth.
     #
-    # === Security and trust
+    # === Choosing skill sources
     #
-    # Configured roots and their contents are fully trusted instruction sources.
-    # The +allowed-tools+ field is metadata shown to the model, not an
-    # authorization boundary. Applications must enforce tool access separately
-    # and keep skill roots non-user-writable.
+    # Skill files become model instructions, so keep configured roots under
+    # application control and non-user-writable. The +allowed-tools+ field tells
+    # the model what a skill expects; the Agent's Tool list and each Tool's
+    # application checks still decide what can run. For a <tt>workspace://</tt>
+    # resource root, the Catalog verifies the named read-only grant and rejects
+    # direct writable aliases it can identify. LittleGhost cannot identify every
+    # alias created by an outer container or mount namespace, so the application
+    # must not expose the same files through another writable bind mount.
     class Catalog
       include Enumerable
 
@@ -40,21 +44,29 @@ module LittleGhost
       SAFE_NAME_PATTERN = /\A[a-zA-Z0-9_-]+\z/ # :nodoc:
 
       # Loads valid skills immediately using the supplied safety limits.
+      # +resource_root+ may be an absolute process-visible path. A
+      # <tt>workspace://name</tt> reference also requires +workspace+ and
+      # +sandbox+; it must resolve to every configured skill root through a
+      # read-only file-tool grant.
       def initialize(
         paths:,
         max_skills: DEFAULT_MAX_SKILLS,
         max_file_bytes: DEFAULT_MAX_FILE_BYTES,
         max_resource_files: DEFAULT_MAX_RESOURCE_FILES,
         only: nil,
-        resource_root: nil
+        resource_root: nil,
+        workspace: nil,
+        sandbox: nil
       )
         @paths = PathSet.new(paths)
         @max_skills = positive_integer(max_skills, :max_skills)
         @max_file_bytes = positive_integer(max_file_bytes, :max_file_bytes)
         @max_resource_files = positive_integer(max_resource_files, :max_resource_files)
         @only = Array(only).map(&:to_s).freeze if only
-        @resource_root = canonical_resource_root(resource_root)
+        @resource_root = ResourceRoot.normalize(resource_root)
+        validate_workspace_resource_root!(workspace, sandbox)
         @skills = load_skills
+        validate_workspace_resource_aliases!(sandbox)
       end
 
       # Yields each Skill in lookup order.
@@ -257,15 +269,83 @@ module LittleGhost
         integer
       end
 
-      def canonical_resource_root(value)
-        return unless value
+      def validate_workspace_resource_root!(workspace, sandbox)
+        return unless @resource_root&.start_with?("workspace://")
+        unless workspace && sandbox
+          raise ConfigurationError, "workspace resource_root requires a Workspace and Sandbox"
+        end
+        unless sandbox.workspace.equal?(workspace)
+          raise ConfigurationError, "workspace resource_root requires the Sandbox bound to its Workspace"
+        end
+
+        physical_root = File.realpath(workspace.resolve(@resource_root))
+        source_roots = @paths.filter_map do |root|
+          File.realpath(root.path) if Dir.exist?(root.path)
+        end
+        unless source_roots.all? { |source_root| source_root == physical_root }
+          raise ConfigurationError, "workspace resource_root must map to each skill path"
+        end
+        unless sandbox.allows?(:filesystem_read, @resource_root) &&
+            !sandbox.allows?(:filesystem_write, @resource_root)
+          raise ConfigurationError, "workspace resource_root must be tool-readable and read-only"
+        end
+        if writable_tool_grants(sandbox).any? do |grant|
+          source = File.realpath(grant.source)
+          source == physical_root || source.start_with?("#{physical_root}#{File::SEPARATOR}")
+        end
+          raise ConfigurationError, "workspace resource_root must not contain writable file grants"
+        end
+        @workspace_physical_root = physical_root
+      rescue Errno::ENOENT, KeyError, ArgumentError => error
+        raise ConfigurationError, "workspace resource_root is not available: #{error.message}"
+      end
 
-        path = value.to_s
-        if path.include?("\0") || !Pathname.new(path).absolute? || path.split(File::SEPARATOR).include?("..")
-          raise ArgumentError, "resource_root must be an absolute path"
+      def validate_workspace_resource_aliases!(sandbox)
+        return unless @workspace_physical_root
+
+        protected_identities = protected_directory_identities
+        aliased = writable_tool_grants(sandbox).any? do |grant|
+          stat = File.stat(grant.source)
+          protected_identities.include?([stat.dev, stat.ino])
+        end
+        if aliased
+          raise ConfigurationError, "workspace resource_root must not contain writable file grants"
         end
+      rescue Errno::ENOENT, Errno::EACCES => error
+        raise ConfigurationError, "workspace resource_root is not available: #{error.message}"
+      end
 
-        File.expand_path(path).freeze
+      def writable_tool_grants(sandbox)
+        grants = sandbox.respond_to?(:process_grants) ? sandbox.process_grants : sandbox.scope.process_grants
+        grants.select { |grant| grant.tool_visible? && grant.writable? }
+      end
+
+      def protected_directory_identities
+        directories = [@workspace_physical_root]
+        @skills.each_value do |skill|
+          skill_directory = File.dirname(skill.source_path)
+          directories << skill_directory
+          RESOURCE_DIRECTORIES.each do |name|
+            resource_root = File.join(skill_directory, name)
+            collect_resource_directories(resource_root, directories) if File.directory?(resource_root)
+          end
+        end
+        directories.uniq.to_h do |directory|
+          stat = File.stat(directory)
+          [[stat.dev, stat.ino], true]
+        end
+      end
+
+      def collect_resource_directories(directory, directories, depth = 0)
+        return if depth >= MAX_RESOURCE_DEPTH || File.symlink?(directory)
+
+        directories << directory
+        Dir.children(directory).each do |name|
+          child = File.join(directory, name)
+          collect_resource_directories(child, directories, depth + 1) if File.directory?(child)
+        rescue Errno::ENOENT, Errno::EACCES
+          next
+        end
       end
 
       def agent_path(source_path, source_root)