samagotchi 0.31.0 → 0.32.0

data/lib/samagotchi/context_sources.rb

@@ -0,0 +1,452 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "time"
+require_relative "atomic_file"
+require_relative "memory_paths"
+require_relative "paths"
+require_relative "session"
+
+module Samagotchi
+  # Attached context: named external sources a session keeps fresh (a PR, a
+  # thread, a script's output). A Source says how to get the text (a command,
+  # or nothing for a pushed one) and why it's attached; its Snapshot is the
+  # last good text; a session's Subscription is what it has seen and read.
+  # Everything lives under one root, <state dir>/context/, apart from the
+  # session dirs:
+  #   projects/<project_key>/<name>.json           a project's Source
+  #   projects/<project_key>/<name>.snapshot.json  its Snapshot
+  #   sessions/<id>/<name>.json, …snapshot.json    a session's own
+  #   sessions/<id>/subscriptions.json             {name => Subscription}; the worker writes it
+  #   sessions/<id>/muted/<name>                   a marker: this session ignores <name>
+  #   sessions/<id>/declined/<name>                a marker (its hint inside): the user removed <name>
+  # The guardrails protect the root (ProtectedPaths, CHI_TEXT): a source's
+  # command runs later, outside the gate.
+  module ContextSources
+    DIR = "context"
+    NAME_RE = /\A[a-z0-9][a-z0-9-]{0,39}\z/
+    # subscriptions.json shares a session's folder with its sources.
+    RESERVED_NAMES = %w[subscriptions].freeze
+    SCOPES = %w[session project].freeze
+    MIN_EVERY_SECONDS = 30
+    DEFAULT_EVERY_SECONDS = 300
+    TEXT_MAX_BYTES = 1024 * 1024
+    SUMMARY_MAX_CHARS = 200
+    LINE_MAX_CHARS = 300
+    SNAPSHOT_SUFFIX = ".snapshot.json"
+    SUBSCRIPTIONS_FILE = "subscriptions.json"
+    MUTED_DIR = "muted"
+    DECLINED_DIR = "declined"
+
+    # A name, a command, a value the store can't take.
+    class Invalid < ArgumentError; end
+
+    # A source's definition. +cmd+ nil: pushed only (chi context push).
+    # +provider+: the bundle whose context provider made it (a URL), whose
+    # folder its cmd's {bundle_dir} names (ContextProviders.command_for).
+    Source = Data.define(:name, :cmd, :every_seconds, :why, :hint, :scope, :added_by, :created_at, :provider) do
+      def initialize(name:, cmd:, every_seconds:, why:, hint:, scope:, added_by:, created_at:, provider: nil) = super
+
+      def push? = cmd.nil?
+
+      def to_h
+        { "name" => name, "cmd" => cmd, "every_seconds" => every_seconds, "why" => why, "hint" => hint,
+          "scope" => scope, "added_by" => added_by, "created_at" => created_at, "provider" => provider }.compact
+      end
+
+      def self.from_h(data)
+        new(name: data["name"].to_s, cmd: data["cmd"], every_seconds: data["every_seconds"]&.to_i,
+            why: data["why"], hint: data["hint"], scope: data["scope"].to_s, added_by: data["added_by"],
+            created_at: data["created_at"], provider: data["provider"])
+      end
+    end
+
+    # A source's last result. +text+ nil until a fetch or push succeeds;
+    # +serial+ counts the revisions (an absorb that missed some says how
+    # many); +error+ is the last failure, +error_since+ when the failures
+    # began (cleared by a success), so a session hears about each run of
+    # failures once. +summary+, +wake+ and +hint+ come with the revision.
+    # +fetched_at+ is the last success, +checked_at+ the last try (the
+    # poller's clock: a failing source isn't run again every tick).
+    Snapshot = Data.define(:text, :summary, :revision, :serial, :fetched_at, :checked_at, :wake, :hint, :error,
+                           :error_since) do
+      def self.empty
+        new(text: nil, summary: nil, revision: nil, serial: 0, fetched_at: nil, checked_at: nil, wake: false, hint: nil,
+            error: nil, error_since: nil)
+      end
+
+      def to_h
+        { "text" => text, "summary" => summary, "revision" => revision, "serial" => serial,
+          "fetched_at" => fetched_at, "checked_at" => checked_at, "wake" => (wake ? true : nil), "hint" => hint,
+          "error" => error, "error_since" => error_since }.compact
+      end
+
+      def self.from_h(data)
+        new(text: data["text"], summary: data["summary"], revision: data["revision"], serial: data["serial"].to_i,
+            fetched_at: data["fetched_at"], checked_at: data["checked_at"] || data["fetched_at"],
+            wake: data["wake"] == true, hint: data["hint"], error: data["error"], error_since: data["error_since"])
+      end
+
+      def text? = !text.nil?
+
+      # Seconds since the last try; nil for never.
+      def age(now = Time.now)
+        checked_at && (now - Time.iso8601(checked_at))
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # What one session has had of a source: +seen+ the revision its last
+    # note was about (+seen_serial+ that revision's serial), +read+ the
+    # revision context_read last returned, +error_seen+ the error_since it
+    # was told about, +wakes_at+ when a change last woke it (C4).
+    Subscription = Data.define(:name, :seen, :seen_serial, :read, :error_seen, :wakes_at) do
+      def self.blank(name)
+        new(name: name, seen: nil, seen_serial: 0, read: nil, error_seen: nil, wakes_at: nil)
+      end
+
+      def to_h
+        { "seen" => seen, "seen_serial" => seen_serial, "read" => read, "error_seen" => error_seen,
+          "wakes_at" => wakes_at }.compact
+      end
+
+      def self.from_h(name, data)
+        new(name: name, seen: data["seen"], seen_serial: data["seen_serial"].to_i, read: data["read"],
+            error_seen: data["error_seen"], wakes_at: data["wakes_at"])
+      end
+    end
+
+    # What a command printed or a push sent (the contract, ContextSources.parse_output).
+    Fetched = Data.define(:text, :summary, :wake, :hint)
+
+    # A source as one session sees it: the definition, where it lives, and
+    # +shadowed+ for a project source hidden by a session one of its name.
+    Attached = Data.define(:source, :location, :shadowed) do
+      def name = source.name
+      def snapshot = location.snapshot(source.name)
+    end
+
+    # A folder of sources: a project's or a session's.
+    Location = Data.define(:scope, :dir, :key) do
+      def session? = scope == "session"
+
+      def source_path(name) = File.join(dir, "#{ContextSources.check_name!(name)}.json")
+      def snapshot_path(name) = File.join(dir, "#{ContextSources.check_name!(name)}#{SNAPSHOT_SUFFIX}")
+      def lock_path(name) = File.join(dir, "#{ContextSources.check_name!(name)}.lock")
+
+      # @return [Array<Source>] by name
+      def sources
+        return [] unless Dir.exist?(dir)
+
+        Dir.children(dir).sort.filter_map do |file|
+          next unless file.end_with?(".json") && !file.end_with?(SNAPSHOT_SUFFIX) && file != SUBSCRIPTIONS_FILE
+
+          name = file.delete_suffix(".json")
+          name.match?(NAME_RE) ? source(name) : nil
+        end
+      end
+
+      # @return [Source, nil]
+      def source(name)
+        data = ContextSources.read_json(source_path(name))
+        data && Source.from_h(data.merge("name" => name, "scope" => scope))
+      end
+
+      # @raise [Invalid] a source of that name exists here
+      def add(source)
+        FileUtils.mkdir_p(dir)
+        path = source_path(source.name)
+        raise Invalid, "#{source.name} is already attached here (chi context rm #{source.name} first)" if File.exist?(path)
+
+        AtomicFile.write(path, "#{JSON.pretty_generate(source.to_h)}\n")
+        # Added again on purpose: no longer declined.
+        FileUtils.rm_f(declined_path(source.name))
+        source
+      end
+
+      # @return [Boolean] whether there was a source to remove
+      # The lock file stays: a fetch running now still holds it, and a new
+      # source of the name must wait for that fetch (which then finds its
+      # source gone and writes nothing: ContextFetch) instead of opening a
+      # fresh lock beside it.
+      # A session's source removed leaves a declined marker holding its hint
+      # (#declined?): an auto-attach (ctx.context, the github-pr bundle) on
+      # the worker's next start must not bring back what the user took off.
+      def remove(name)
+        removed = source(name)
+        [source_path(name), snapshot_path(name)].each { |path| FileUtils.rm_f(path) }
+        decline(name, removed.hint) if removed && session?
+        !removed.nil?
+      end
+
+      # Whether the user removed +name+ from this session (#remove).
+      def declined?(name) = File.exist?(declined_path(name))
+
+      # The hints (often URLs) of the sources removed here.
+      def declined_hints
+        folder = File.join(dir, DECLINED_DIR)
+        return [] unless Dir.exist?(folder)
+
+        Dir.children(folder).sort.filter_map do |file|
+          hint = File.read(File.join(folder, file)).strip
+          hint.empty? ? nil : hint
+        rescue SystemCallError
+          nil
+        end
+      end
+
+      # @return [Snapshot] Snapshot.empty when there is none yet
+      def snapshot(name)
+        data = ContextSources.read_json(snapshot_path(name))
+        data ? Snapshot.from_h(data) : Snapshot.empty
+      end
+
+      # @return [Time, nil] the snapshot file's mtime: the worker's cheap "anything new?"
+      def snapshot_mtime(name)
+        File.mtime(snapshot_path(name))
+      rescue SystemCallError
+        nil
+      end
+
+      def write_snapshot(name, snapshot)
+        FileUtils.mkdir_p(dir)
+        AtomicFile.write(snapshot_path(name), JSON.generate(snapshot.to_h))
+        snapshot
+      end
+
+      # A fetch or a push that worked: a new revision, or the same text
+      # fetched again (only fetched_at moves; its summary and wake are
+      # ignored). Clears the error.
+      # @return [Snapshot] the one written
+      def record_text(name, fetched, now: Time.now)
+        previous = snapshot(name)
+        revision = ContextSources.revision_of(fetched.text)
+        stamp = now.utc.iso8601
+        written = if revision == previous.revision
+                    previous.with(fetched_at: stamp, checked_at: stamp, error: nil, error_since: nil)
+                  else
+                    Snapshot.new(text: fetched.text, revision: revision, serial: previous.serial + 1, fetched_at: stamp,
+                                 checked_at: stamp, summary: fetched.summary || ContextSources.plain_summary(previous.text, fetched.text),
+                                 wake: fetched.wake, hint: fetched.hint || previous.hint, error: nil, error_since: nil)
+                  end
+        write_snapshot(name, written)
+      end
+
+      # Run the block holding <name>.lock (blocking), the lock a fetch
+      # holds while it runs and records: a push's read-modify-write of the
+      # snapshot (its serial) doesn't interleave with another writer.
+      def locked(name)
+        FileUtils.mkdir_p(dir)
+        File.open(lock_path(name), File::RDWR | File::CREAT, 0o644) do |lock|
+          lock.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      # A fetch that failed: the last good text stays.
+      # @return [Snapshot] the one written
+      def record_error(name, message, now: Time.now)
+        previous = snapshot(name)
+        # Microseconds: two runs of failures never share a start.
+        stamp = now.utc.iso8601(6)
+        write_snapshot(name, previous.with(error: ContextSources.one_line(message, LINE_MAX_CHARS),
+                                           error_since: previous.error_since || stamp, checked_at: stamp))
+      end
+
+      def declined_path(name) = File.join(dir, DECLINED_DIR, ContextSources.check_name!(name))
+
+      def decline(name, hint)
+        FileUtils.mkdir_p(File.join(dir, DECLINED_DIR))
+        AtomicFile.write(declined_path(name), "#{hint}\n")
+      end
+
+      # Session only: the markers and the worker's subscription file.
+      def muted?(name) = File.exist?(File.join(dir, MUTED_DIR, ContextSources.check_name!(name)))
+
+      def mute(name)
+        FileUtils.mkdir_p(File.join(dir, MUTED_DIR))
+        FileUtils.touch(File.join(dir, MUTED_DIR, ContextSources.check_name!(name)))
+      end
+
+      def unmute(name) = FileUtils.rm_f(File.join(dir, MUTED_DIR, ContextSources.check_name!(name)))
+
+      # @return [Hash{String => Subscription}]
+      def subscriptions
+        data = ContextSources.read_json(File.join(dir, SUBSCRIPTIONS_FILE)) || {}
+        data.to_h { |name, value| [name, Subscription.from_h(name, value.is_a?(Hash) ? value : {})] }
+      end
+
+      def subscription(name) = subscriptions[name] || Subscription.blank(name)
+
+      # Only the session's worker (its absorb step, its context_read) calls this.
+      def write_subscriptions(subs)
+        FileUtils.mkdir_p(dir)
+        AtomicFile.write(File.join(dir, SUBSCRIPTIONS_FILE), JSON.generate(subs.transform_values(&:to_h)))
+      end
+
+      def update_subscription(name)
+        subs = subscriptions
+        subs[name] = yield(subs[name] || Subscription.blank(name))
+        write_subscriptions(subs)
+        subs[name]
+      end
+    end
+
+    module_function
+
+    # <state dir>/context; +state_dir+ is the sessions dir (Session.default_state_dir).
+    def root(state_dir: nil)
+      File.join(File.dirname(state_dir || Session.default_state_dir), DIR)
+    end
+
+    def session_location(session_id, state_dir: nil)
+      Location.new(scope: "session", dir: File.join(root(state_dir: state_dir), "sessions", Session.check_id!(session_id)),
+                   key: session_id)
+    end
+
+    def project_location(project_key, state_dir: nil)
+      Location.new(scope: "project", dir: File.join(root(state_dir: state_dir), "projects", project_key.to_s), key: project_key)
+    end
+
+    # The project a session's sources come from: nil when it is in no repo.
+    # @param project_root [String, nil] Session#project_root
+    def project_location_for(project_root, state_dir: nil)
+      return nil if project_root.to_s.empty?
+
+      project_location(project_key_of(project_root), state_dir: state_dir)
+    end
+
+    # MemoryPaths.project_key for a root already resolved.
+    def project_key_of(root)
+      "#{File.basename(root)}_#{Digest::MD5.hexdigest(root)[0..7]}"
+    end
+
+    # A session's sources: its own, then the project's it doesn't shadow
+    # (+shadowed+ lists those too, marked).
+    # @return [Array<Attached>]
+    def attached(session_id, project_root:, state_dir: nil, shadowed: false)
+      own = session_location(session_id, state_dir: state_dir)
+      list = own.sources.map { |source| Attached.new(source: source, location: own, shadowed: false) }
+      project = project_location_for(project_root, state_dir: state_dir)
+      return list unless project
+
+      names = list.map(&:name)
+      project.sources.each do |source|
+        hidden = names.include?(source.name)
+        list << Attached.new(source: source, location: project, shadowed: hidden) if !hidden || shadowed
+      end
+      list
+    end
+
+    # Where a project's source runs: the project root when it is a checkout
+    # (its .git is there), else +fallback+ (the session's folder): a bare
+    # repo, proj/.bare or --separate-git-dir makes the root the git dir
+    # itself (MemoryPaths.project_root), and a command run there sees no
+    # files.
+    def project_cwd(project_root, fallback)
+      root = project_root.to_s
+      !root.empty? && File.exist?(File.join(root, ".git")) ? root : fallback
+    end
+
+    # A deleted session's sources, snapshots, subscriptions and markers.
+    # @return [Array<String>] the paths removed
+    def remove_session(session_id, state_dir: nil)
+      return [] unless Session.valid_id?(session_id.to_s)
+
+      dir = session_location(session_id, state_dir: state_dir).dir
+      return [] unless Dir.exist?(dir)
+
+      FileUtils.rm_rf(dir)
+      [dir]
+    rescue SystemCallError
+      []
+    end
+
+    # @return [String] +name+
+    # @raise [Invalid]
+    def check_name!(name)
+      name = name.to_s
+      unless name.match?(NAME_RE)
+        raise Invalid, "#{name.inspect} isn't a source name: lowercase letters, digits and -, up to 40, starting with a letter or digit"
+      end
+      raise Invalid, "#{name} is a reserved name" if RESERVED_NAMES.include?(name)
+
+      name
+    end
+
+    # @raise [Invalid] below MIN_EVERY_SECONDS or not a number
+    def check_every!(value)
+      return nil if value.nil?
+
+      seconds = Integer(value.to_s, 10, exception: false)
+      raise Invalid, "--every takes seconds, not #{value.inspect}" unless seconds
+      raise Invalid, "--every is #{seconds}; the least is #{MIN_EVERY_SECONDS} seconds" if seconds < MIN_EVERY_SECONDS
+
+      seconds
+    end
+
+    def revision_of(text) = Digest::SHA256.hexdigest(text.to_s)
+
+    # The contract: stdout that parses as a JSON object with a string "text"
+    # is {text, summary, wake, hint}; anything else is all text. Unknown
+    # keys are ignored; summary and hint become one line, cut.
+    # @return [Fetched]
+    # @raise [Invalid] nothing to keep (empty, or over TEXT_MAX_BYTES)
+    def parse_output(raw)
+      raw = raw.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+      data = json_object(raw)
+      fetched = if data.is_a?(Hash) && data["text"].is_a?(String)
+                  Fetched.new(text: data["text"].scrub, summary: one_line(data["summary"], SUMMARY_MAX_CHARS),
+                              wake: data["wake"] == true, hint: one_line(data["hint"], LINE_MAX_CHARS))
+                else
+                  Fetched.new(text: raw, summary: nil, wake: false, hint: nil)
+                end
+      raise Invalid, "the output is empty" if fetched.text.strip.empty?
+      if fetched.text.bytesize > TEXT_MAX_BYTES
+        raise Invalid, "the text is #{fetched.text.bytesize} bytes; the limit is 1 MiB (#{TEXT_MAX_BYTES} bytes)"
+      end
+
+      fetched
+    end
+
+    def json_object(raw)
+      return nil unless raw.lstrip.start_with?("{")
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # chi's summary of a plain-text change: "content changed (+12/−3 lines)",
+    # or the size of the first text.
+    def plain_summary(before, after)
+      return "#{after.lines.size} #{after.lines.size == 1 ? "line" : "lines"} of text" if before.nil?
+
+      require_relative "text_diff"
+      diff = TextDiff.unified(before, after, max_lines: 0, max_bytes: 0)
+      "content changed (+#{diff[:added]}/−#{diff[:removed]} lines)"
+    end
+
+    # One line, whitespace collapsed, cut at +max+ chars with "…"; nil for blank.
+    def one_line(value, max)
+      return nil unless value.is_a?(String)
+
+      line = value.scrub.gsub(/\s+/, " ").strip
+      return nil if line.empty?
+
+      line.length > max ? "#{line[0, max - 1]}…" : line
+    end
+
+    def read_json(path)
+      return nil unless File.file?(path)
+
+      data = JSON.parse(File.read(path))
+      data.is_a?(Hash) ? data : nil
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+  end
+end

data/lib/samagotchi/engine.rb

@@ -660,7 +660,7 @@ module Samagotchi
         replace_session_messages(session, Array(session.messages) + [message])
         announce({ type: :context_added, session_id: session.id, note_id: note[:note_id], source: note[:source],
                    label: ContextNote.label_of(message), from_session: note[:from_session],
-                   from_cwd: note[:from_cwd], text: note[:text],
+                   from_cwd: note[:from_cwd], text: note[:text], context_source: note[:context_source],
                    created_at: note[:created_at] }.compact)
         message
       end
@@ -1192,6 +1192,7 @@ module Samagotchi
       client_id = origin.is_a?(Hash) ? origin[:client_id].to_s : ""
       source = if client_id.start_with?("#{Tools::Delegate::CLIENT_PREFIX}:") then "delegate"
                elsif client_id.start_with?(ChildReports::CLIENT_PREFIX) then "delegate_report"
+               elsif client_id.start_with?(Steer::CONTEXT_CLIENT_PREFIX) then "context"
                elsif client_id == SessionManager::REMINDER_CLIENT_ID then "reminder"
                else "client"
                end
@@ -1462,6 +1463,7 @@ module Samagotchi
     PeerView = Struct.new(:engine) do
       def session_id = engine.session&.id
       def cwd = engine.session&.working_directory
+      def project_root = engine.session&.project_root
       def state_dir = engine.peer_state_dir
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
       def relay = engine.relay_peer
@@ -1598,6 +1600,9 @@ module Samagotchi
     #   stored/validated before :turn_started (which carries their refs), and
     #   a model known not to see images fails the turn before anything of it
     #   is kept (VisionUnsupported).
+    # @param id [String, nil] the turn's id (a new uuid when nil): a caller
+    #   that put the turn's first message in the session already (a context
+    #   wake's note) names it with this id
     #
     # An Interrupt (SIGINT) cancels the turn: the pre-turn conversation plus
     # the prompt is kept in the session and :turn_canceled is emitted, then the
@@ -1608,9 +1613,9 @@ module Samagotchi
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
     def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
-                 images: [])
+                 images: [], id: nil)
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
-                                         continue: continue)
+                                         continue: continue, id: id)
       begin
         # A Stop cuts the /props probes this thread makes for the turn
         # (window, served model, vision) instead of waiting their timeout.
@@ -1654,7 +1659,7 @@ module Samagotchi
     # The turn's state before anything can fail it: the session running,
     # the turn flag, its cancel controller and sink. The cross-thread state
     # is set here and cleared in #release_turn only.
-    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:)
+    def begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id: nil)
       # Track the active session for recap and status snapshot.
       @session = session
       # status is turn state: running now, idle again before the turn's end
@@ -1677,7 +1682,7 @@ module Samagotchi
 
       Turn.new(session: session, prompt: continue ? nil : prompt, continue: continue, on_event: on_event,
                controller: effective_controller, origin: origin, started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
-               id: SecureRandom.uuid)
+               id: id || SecureRandom.uuid)
     end
     private :begin_turn
 

data/lib/samagotchi/guardrail_wiring.rb

@@ -182,11 +182,13 @@ module Samagotchi
     def protected_paths
       @protected ||= begin
         require_relative "memory_bundle/provenance"
+        require_relative "context_sources"
         Guardrails::ProtectedPaths.new(
           store_dir: File.dirname(@approvals.path),
           bundles_dir: MemoryBundle::Provenance.bundles_dir,
           config_path: Samagotchi::ConfigFile.global_path,
-          hooks_dir: Hooks::Loader.hooks_dir
+          hooks_dir: Hooks::Loader.hooks_dir,
+          context_dir: ContextSources.root
         )
       end
     end

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -5,6 +5,7 @@ require_relative "../paths"
 require_relative "../memory_paths"
 require_relative "../hooks/loader"
 require_relative "approval"
+require_relative "verdict"
 require_relative "protected_paths"
 require_relative "parent_continue"
 
@@ -40,12 +41,13 @@ module Samagotchi
       # They survive a PTY wrapper (script, expect). The docs list them too
       # (guardrails.md, sub-agent.md).
       AGENT_MARKERS = ["CLAUDECODE", "AI_AGENT", "CODEX_THREAD_ID", PARENT_SESSION_ENV].freeze
-      # Rules that ask about chi's own config and hooks: the core
-      # ProtectedPaths asks and the guardrails bundle's shell rule.
-      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi].freeze
-      # A shell command naming chi's config, hooks or guardrails as text
-      # (broad: a parent may not allow what only looks like one).
-      CHI_TEXT = %r{\.config/samagotchi|samagotchi/config\.yml|samagotchi/hooks|samagotchi/guardrails|memories/\.bundles}
+      # Rules only the user may allow (Verdict::PROTECTED_RULES).
+      PROTECTED_RULES = Verdict::PROTECTED_RULES
+      # A shell command naming chi's config, hooks, guardrails or attached
+      # context as text (broad: a parent may not allow what only looks like
+      # one). samagotchi/context stops before a word character or a dot, so
+      # chi's own lib/samagotchi/context_*.rb isn't one.
+      CHI_TEXT = %r{\.config/samagotchi|samagotchi/config\.yml|samagotchi/hooks|samagotchi/guardrails|samagotchi/context(?![\w.])|memories/\.bundles}
       # The guardrails bundle's shell-touches-chi, for a word it can't
       # resolve to a path (Guardrails::ShellPaths): CHI_TEXT and .git/hooks.
       CHI_SHELL_TEXT = Regexp.union(CHI_TEXT, %r{\.git/hooks})
@@ -110,7 +112,7 @@ module Samagotchi
       def chi_dirs
         hooks = begin Hooks::Loader.hooks_dir rescue nil end
         bundles = begin MemoryPaths.bundles_dir rescue nil end
-        [ConfigFile.config_dir, hooks, File.join(Paths.state_dir, "guardrails"), bundles]
+        [ConfigFile.config_dir, hooks, File.join(Paths.state_dir, "guardrails"), bundles, File.join(Paths.state_dir, "context")]
           .compact.map { |dir| dir.to_s.chomp("/") }.reject(&:empty?).uniq
       end
 

data/lib/samagotchi/guardrails/protected_paths.rb

@@ -5,9 +5,10 @@ module Samagotchi
     # Core checks on what the file tools (write, edit, memory_write) touch,
     # after the hooks and before the rules. Paths are compared with
     # symlinks resolved (on the longest existing parent).
-    #   deny: the approval store's dir and installed bundles (.bundles/:
-    #         hooks, rules, manifests); nothing legitimate writes there
-    #         through the file tools.
+    #   deny: the approval store's dir, installed bundles (.bundles/:
+    #         hooks, rules, manifests) and attached context (a source's
+    #         command runs later, outside the gate; chi context writes
+    #         it); nothing legitimate writes there through the file tools.
     #   ask (once / session): config.yml and the plain hooks dir. The
     #         system bundle's config protocol edits config.yml with
     #         write/edit, so this keeps the user in the loop without
@@ -22,10 +23,12 @@ module Samagotchi
       # @param bundles_dir [String] <memories>/.bundles
       # @param config_path [String] config.yml
       # @param hooks_dir [String] the plain hooks dir
-      def initialize(store_dir:, bundles_dir:, config_path:, hooks_dir:)
+      # @param context_dir [String, nil] <state dir>/context (ContextSources.root)
+      def initialize(store_dir:, bundles_dir:, config_path:, hooks_dir:, context_dir: nil)
         @deny = [
           ["guardrail-store", store_dir, "the approval store belongs to the user"],
-          ["installed-bundles", bundles_dir, "installed bundles (hooks, rules, manifests) are changed by chi bundle install"]
+          ["installed-bundles", bundles_dir, "installed bundles (hooks, rules, manifests) are changed by chi bundle install"],
+          ["chi-context", context_dir, "attached context sources run commands; change them with chi context"]
         ]
         @ask = [
           ["chi-config", config_path, "changes chi's config.yml"],

data/lib/samagotchi/guardrails/shell_lex.rb

@@ -33,15 +33,6 @@ module Samagotchi
         Lexer.new(text).tokens
       end
 
-      # lex's tokens, each with the range of +text+ it was read from
-      # appended ([:word, "x", specials, 0...1] / [:op, "&&", 2...4]), for a
-      # display that slices the original text. A heredoc body's range is
-      # the body and its terminator line. lex itself is unchanged by this.
-      def self.lex_with_spans(text)
-        lexer = Lexer.new(text)
-        lexer.tokens.zip(lexer.spans).map { |token, span| [*token, span] }
-      end
-
       # The token stream split at operators into word lists; ( and ) become
       # :open / :close markers.
       def self.simple_commands(tokens)

data/lib/samagotchi/guardrails/verdict.rb

@@ -5,9 +5,17 @@ module Samagotchi
     # The gate's verdict for one tool call. Voters (hooks now, rules later)
     # call #deny! or #ask!; the strictest vote wins (deny > ask > allow) and
     # a vote never relaxes it, so a deny is sticky. Of two equal votes the
-    # first one stays.
+    # first one stays, except that a protected rule's ask (PROTECTED_RULES)
+    # takes over an unprotected ask: its rule id is what a parent's answer
+    # and a stored approval are checked against, and the offered scopes
+    # narrow to both asks' common ones.
     class Verdict
       STRICTNESS = { allow: 0, ask: 1, deny: 2 }.freeze
+      # Rules that ask about chi's own config and hooks: the core
+      # ProtectedPaths asks and the guardrails bundle's shell rule; and a
+      # command source for attached context (it runs later, ungated). Only
+      # the user may allow them (ParentApprovals).
+      PROTECTED_RULES = %w[chi-config chi-hooks shell-touches-chi chi-context-cmd].freeze
       SCOPES = %w[once session repo rule].freeze
       DO_NOT_RETRY = "Do not retry it or reach the same result another way; ask the user how to proceed."
 
@@ -46,13 +54,18 @@ module Samagotchi
       # @param scopes [Array<String>, nil] which approval scopes the user may
       #   pick (default all of SCOPES)
       def ask!(reason, scopes: nil, rule: nil, source: nil, decided_by: "hook")
+        earlier = ask? ? @scopes : nil
         return self unless vote(:ask, reason, rule: rule, source: source, decided_by: decided_by)
 
         picked = Array(scopes).map(&:to_s) & SCOPES
-        @scopes = picked.empty? ? SCOPES : picked
+        picked = SCOPES if picked.empty?
+        picked &= earlier if earlier
+        @scopes = picked.empty? ? %w[once] : picked
         self
       end
 
+      def self.protected_rule?(rule) = PROTECTED_RULES.include?(rule.to_s)
+
       # A before_tool_call hook set the old event[:blocked] flag. Its model
       # text stays "blocked by guardrail: <reason>".
       def legacy_deny!(reason)
@@ -118,7 +131,7 @@ module Samagotchi
       end
 
       def vote(decision, reason, decided_by:, rule: nil, source: nil)
-        return false unless STRICTNESS.fetch(decision) > STRICTNESS.fetch(@decision)
+        return false unless STRICTNESS.fetch(decision) > STRICTNESS.fetch(@decision) || takes_over?(decision, rule)
 
         @decision = decision
         @reason = reason.to_s.strip
@@ -129,6 +142,11 @@ module Samagotchi
         @legacy = false
         true
       end
+
+      # A protected rule's ask over an unprotected one.
+      def takes_over?(decision, rule)
+        decision == :ask && ask? && Verdict.protected_rule?(rule) && !Verdict.protected_rule?(@rule)
+      end
     end
   end
 end