samagotchi 0.35.0 → 0.37.0

data/lib/samagotchi/bundles/mcp/plugin.rb

@@ -27,11 +27,14 @@
 # A server that doesn't start, answer or list its tools is skipped with a
 # notice; the rest of chi works. One that exits mid-session starts again on
 # its next call, at most MAX_RESTARTS times a session. /mcp lists the
-# servers and their tools.
+# servers and their tools, with an estimate of the tokens their
+# definitions take in every request.
 require "digest"
 require "json"
 require "open3"
 require "samagotchi/process_group"
+require "samagotchi/token_usage"
+require "samagotchi/tool_declarations"
 require "time"
 require "shellwords"
 require "tmpdir"
@@ -47,6 +50,8 @@ class Plugin
   CACHE_TTL = 24 * 60 * 60
   # Restarts of a server that exited, per session.
   MAX_RESTARTS = 3
+  # The states whose server's tools the model has (what publish declares).
+  OFFERED = %i[running cached exited].freeze
   IMAGE_EXT = { "image/png" => "png", "image/jpeg" => "jpg", "image/gif" => "gif", "image/webp" => "webp" }.freeze
 
   # A JSON-RPC client for one MCP server over stdio: newline-delimited JSON
@@ -242,13 +247,21 @@ class Plugin
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end
 
+  # One tool chi offers from a server (the tools: filter applied): +name+
+  # is the server's, +chi_name+ the model's (mcp_<server>_<tool>), +schema+
+  # its inputSchema (an empty object when it has none). +error+ is why
+  # declaring it failed (a name clash, a bad schema), nil when the model
+  # has it.
+  McpTool = Data.define(:server, :name, :chi_name, :description, :schema, :error)
+
   # One configured server: its service, state and tools. +listed+ is its
   # tools/list as the server answers it (what the cache keeps), +tools+
-  # the ones chi offers (the tools: filter applied, each with chi_name).
+  # the ones chi offers (McpTool each; #declare swaps in a whole new
+  # list), +tokens+ their definitions' estimated size (#definition_tokens).
   # +client+ is the running process's (a restart replaces it; the
   # service's stop closes the current one), +restarts+ how many it had.
   Server = Struct.new(:name, :config, :service, :state, :error, :tools, :listed, :timeout, :cwd, :command, :env,
-                      :digest, :cached_at, :relist, :relisting, :client, :restarts, keyword_init: true)
+                      :digest, :cached_at, :relist, :relisting, :client, :restarts, :tokens, keyword_init: true)
 
   def initialize(settings = {})
     @settings = settings
@@ -278,7 +291,7 @@ class Plugin
     configs = {} unless configs.is_a?(Hash)
     @servers = configs.map do |name, config|
       server = Server.new(name: name.to_s, config: config.is_a?(Hash) ? config : {}, state: :starting, tools: [],
-                          restarts: 0)
+                          restarts: 0, tokens: 0)
       server.timeout = positive(server.config["timeout"]) || @timeout
       resolve(server, ctx)
       server.service = chi.service(name) { |svc| start(server, svc, ctx) }
@@ -506,24 +519,48 @@ class Plugin
   # ── Tools ─────────────────────────────────────────────────────────────
 
   # Declare the server's tools on +target+ (chi at load, or the set of
-  # chi.replace_tools later), the tools: filter applied.
+  # chi.replace_tools later), the tools: filter applied. Their estimated
+  # tokens go to the log when they changed.
   def declare(target, server, ctx)
     wanted = server.config["tools"] && Array(server.config["tools"]).map(&:to_s)
-    tools = server.listed.map(&:dup)
-    tools = tools.select { |tool| wanted.any? { |w| File.fnmatch(w, tool["name"], File::FNM_EXTGLOB) } } if wanted
-    server.tools = tools
-    tools.each do |tool|
-      name = tool_name(server.name, tool["name"])
-      target.tool(name, description(tool), schema: tool["inputSchema"] || { "type" => "object", "properties" => {} },
-                                           label: "#{server.name}: #{tool["name"]}", preview: ->(args) { preview(args) }) do |args, call_ctx|
-        call(server, tool["name"], args, call_ctx)
+    listed = server.listed
+    listed = listed.select { |tool| wanted.any? { |w| File.fnmatch(w, tool["name"], File::FNM_EXTGLOB) } } if wanted
+    tokens = 0
+    tools = listed.map do |listed_tool|
+      tool = McpTool.new(server: server.name, name: listed_tool["name"],
+                         chi_name: tool_name(server.name, listed_tool["name"]), description: description(listed_tool),
+                         schema: listed_tool["inputSchema"] || { "type" => "object", "properties" => {} }, error: nil)
+      target.tool(tool.chi_name, tool.description, schema: tool.schema,
+                                                   label: "#{server.name}: #{tool.name}", preview: ->(args) { preview(args) }) do |args, call_ctx|
+        call(server, tool, args, call_ctx)
       end
-      tool["chi_name"] = name
+      tokens += definition_tokens(tool.chi_name, tool.description, tool.schema)
+      tool
     rescue ArgumentError => e
-      text = "MCP tool #{server.name}/#{tool["name"]} left out: #{e.message}"
+      text = "MCP tool #{server.name}/#{tool.name} left out: #{e.message}"
       ctx.notify(text, level: :warn) unless @left_out.include?(text)
       @left_out << text
+      tool.with(error: e.message)
     end
+    # Whole, in one swap: a reader on another thread never sees half a list.
+    server.tools = tools.freeze
+    return if tokens == server.tokens
+
+    server.tokens = tokens
+    ctx.log.info("mcp_tools_estimated", server: server.name, tools: offered(server).size, tokens: tokens)
+  end
+
+  # The server's tools the model has (declared without an error).
+  def offered(server) = server.tools.reject(&:error)
+
+  # A tool's definition as the chat path sends it (LLM::ChatLoop#tool_definitions:
+  # the chat schema, wrapped as a function), in estimated tokens
+  # (TokenUsage::CHARS_PER_TOKEN). The native prompts (Gemma, Qwen) render a
+  # flatter schema, so it is an upper bound there.
+  def definition_tokens(name, description, schema)
+    spec = Samagotchi::Plugin::Api.tool_spec(name, description, schema: schema) { nil }
+    function = Samagotchi::ToolDeclarations.chat_schemas([spec[:schema]]).first.slice(:name, :description, :parameters)
+    Samagotchi::TokenUsage.estimate(JSON.generate({ type: "function", function: function }))
   end
 
   # The servers' tools changed after load (a live list that differs from
@@ -532,7 +569,7 @@ class Plugin
   def publish(ctx)
     @publish.synchronize do
       @chi.replace_tools do |set|
-        @servers.each { |server| declare(set, server, ctx) if %i[running cached exited].include?(server.state) }
+        @servers.each { |server| declare(set, server, ctx) if OFFERED.include?(server.state) }
       end
     end
   end
@@ -554,8 +591,8 @@ class Plugin
     line.length > PREVIEW_CHARS ? "#{line[0, PREVIEW_CHARS - 1]}…" : line
   end
 
-  # A tools/call, as the model's tool result. A cached server starts
-  # here, on its first call.
+  # A tools/call of +tool+ (McpTool), as the model's tool result. A cached
+  # server starts here, on its first call.
   def call(server, tool, args, ctx)
     return "Error: MCP server #{server.name} didn't start: #{server.error}" if server.state == :failed
 
@@ -568,9 +605,9 @@ class Plugin
              end
     return client if client.is_a?(String)
 
-    result = client.request("tools/call", { name: tool, arguments: args }, timeout: server.timeout,
-                                                                           cancelled: -> { ctx.cancelled? })
-    text, images = content(result, server, tool)
+    result = client.request("tools/call", { name: tool.name, arguments: args }, timeout: server.timeout,
+                                                                                cancelled: -> { ctx.cancelled? })
+    text, images = content(result, server, tool.name)
     return "Error: #{text.empty? ? "the tool failed" : text}" if result["isError"]
 
     images.empty? ? text : Samagotchi::Plugin::ToolResult.new(text, images: images)
@@ -750,20 +787,24 @@ class Plugin
   def listing
     return "No servers. Add them in config.yml under `bundles: mcp: servers:` (docs/plugins.md, The mcp bundle)." if @servers.empty?
 
-    @servers.map do |server|
+    servers = @servers.map do |server|
       head = "**#{server.name}**: #{state_text(server)}"
       # Sorted: a server lists its tools in its own (often grouped) order.
-      tools = server.tools.map { |tool| tool["chi_name"] }.compact.sort
+      tools = offered(server).map(&:chi_name).sort
       tools.empty? ? head : "#{head}\n#{tools.map { |t| "- `#{t}`" }.join("\n")}"
-    end.join("\n\n")
+    end
+    total = @servers.sum { |server| OFFERED.include?(server.state) ? server.tokens : 0 }
+    [*servers, "Total: ~#{thousands(total)} tokens of tool definitions in every request " \
+               "(estimated: their JSON as the chat API gets it, ÷ #{format("%g", Samagotchi::TokenUsage::CHARS_PER_TOKEN)})."]
+      .join("\n\n")
   end
 
   def state_text(server)
     case server.state
-    when :cached then "cached (not started), #{server.tools.size} tool#{"s" unless server.tools.size == 1}"
+    when :cached then "cached (not started), #{server.tools.size} tool#{"s" unless server.tools.size == 1}, #{tokens_text(server)}"
     when :running
-      count = server.tools.count { |tool| tool["chi_name"] }
-      "running (pid #{server.client.pid}), #{count} tool#{"s" unless count == 1}"
+      count = offered(server).size
+      "running (pid #{server.client.pid}), #{count} tool#{"s" unless count == 1}, #{tokens_text(server)}"
     when :starting then "starting"
     else "#{server.state == :failed ? "failed" : "stopped"}: #{server.error}"
     end
@@ -771,6 +812,10 @@ class Plugin
     "stopped"
   end
 
+  def tokens_text(server) = "~#{thousands(server.tokens)} tokens"
+
+  def thousands(number) = number.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+
   def positive(value)
     number = Float(value.to_s, exception: false)
     number&.positive? ? number : nil

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.35.0
+version: 0.37.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:37063eb74fdcb4cde748f17193ff23f832723eb38f81aff086f48f410ce7497b
   config_modification_protocol.md: sha256:ec0b0c7023dbf03b93879e51cd5cdc38b22d43a2e5984ee11e8542ace077c3be
-  memory_guide.md: sha256:63d5d7f7d704e6ce7e28dd99e532b714c1b9f7acf548092404248d8ca5385b80
+  memory_guide.md: sha256:f7049304a333be842b761037bab5c8e31e890b8f4ad12f092b14ee8deb053c51
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -33,14 +33,16 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 - Parameters: `name: "entry_name"`, `content: "..."`, `scope: "project"|"system"`, optional `description: "one-liner"`, optional `current_model_only: true`.
 - `name` is the entry name **without** `.md` (the tool adds it). Use `name`, **not** `path` — `path` belongs to the file tools and is ignored here. `name: "index"` is a verbatim write to `index.md` (no auto-index update) — rarely needed.
 - `scope` is **required** — never omit. Prefer `project` for repo conventions, `system` for user preferences.
-- `description` is appended to the managed `index.md` line (`— description`). Replaces previous description if given; otherwise preserves existing one.
+- `description` is appended to the managed `index.md` line (`— description`): one line, at most 200 characters (longer is refused; newlines become spaces). Replaces previous description if given; a missing or blank one preserves the existing one.
+- To change only the description, pass `name`, `scope` and `description` without `content`: the index line changes (its date becomes today), the file stays as it is. The memory must exist in that scope.
+- To remove a memory, pass `name`, `scope` and `remove: true` (nothing else): its file and model overlays move to the bundle trash (`chi bundle trash` lists and empties it) and its index line goes, a dangling line too. Only when the user asked or a skill's steps say so; the guardrails ask the user first. A memory a bundle installed is refused: `chi bundle uninstall` owns it.
 - For a small change to an existing memory (a step, a line), `edit` its file instead of rewriting it all: the path is in `memory_write`'s result and the scope dirs are in the prompt. Its index line is refreshed either way.
 - On success returns `Memory 'name' saved to <scope> scope (N bytes). File written: <path> Index line refreshed automatically.` — confirm `bytes` and `scope`; the index needs nothing from you.
 
 **When to write:**
 - After learning a durable preference (e.g. commit style, test command, coding guideline) that the user confirmed or you observed repeatedly — ask before overwriting existing entries where appropriate.
 - Keep entries small and focused (one topic per file). Use clear filenames: `commit_preferences`, `testing_guide`, `project_conventions`.
-- Never store secrets, tokens, or transient state. Memories are shared via bundles.
+- Never store secrets, tokens, or transient state. Memories are shared via bundles. One exception: a skill may keep a working handoff memory (its steps say so) whose status is its description, removed when the work is done.
 
 **Placeholders:**
 - Content may contain placeholder hints written as double-curly braces around a name (e.g., test_command, language). Detected by `Placeholder` (`Placeholder::PLACEHOLDER_RE`) — install warns but does not fail. Fill them when you write. The placeholder syntax is two opening braces, a name, two closing braces.

data/lib/samagotchi/cli/command.rb

@@ -5,9 +5,9 @@ require_relative "exit"
 module Samagotchi
   module CLI
     # The usage side of a subcommand: its error lines, usage errors (exit 2)
-    # and help. The including class sets @stdout and @stderr and defines
-    # #command_name ("chi send"); its usage text is USAGE unless it
-    # overrides #usage_text.
+    # and help, and its piped stdin. The including class sets @stdout and
+    # @stderr (@stdin for #read_stdin) and defines #command_name ("chi
+    # send"); its usage text is USAGE unless it overrides #usage_text.
     module Command
       HELP_WORDS = %w[-h --help help].freeze
 
@@ -47,6 +47,30 @@ module Samagotchi
 
         parsed
       end
+
+      # The including class's @stdin, read only when it is a pipe or a
+      # file. A terminal means nobody piped anything in, and a socket a
+      # launcher or an agent's shell passes down may never close: waiting
+      # on either would hang a script. (A pipe the caller never closes
+      # still hangs, as it would for cat.)
+      # @return [String, nil] nil for a terminal or a socket
+      def read_stdin
+        return nil if @stdin.respond_to?(:tty?) && @stdin.tty?
+
+        if @stdin.respond_to?(:stat)
+          stat = @stdin.stat
+          return nil unless stat.pipe? || stat.file?
+        end
+
+        @stdin.read
+      end
+
+      # +text+ as UTF-8 whatever the locale says: with no LANG/LC_* (an app
+      # started from Finder, launchd) stdin reads as US-ASCII and ARGV as
+      # binary. Invalid bytes become U+FFFD rather than an error.
+      def utf8(text)
+        text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
+      end
     end
   end
 end

data/lib/samagotchi/config.rb

@@ -89,6 +89,15 @@ module Samagotchi
       # delivers it there without triage.
       Entry.new(key: "broadcast.active_hours",   yaml_path: %w[broadcast active_hours],   type: :float,   default: 8.0,             expose: %i[env config]),
       Entry.new(key: "broadcast.ticket_pattern", yaml_path: %w[broadcast ticket_pattern], type: :string,  default: '\b[A-Z][A-Z0-9]+-\d+\b', expose: %i[env config]),
+      # The triage model that judges a recipient no tag matched (Broadcast::TriageModel): unset, recap.*'s, then
+      # default.model. At most triage_parallel requests at a time, all within triage_deadline seconds (the rest are
+      # delivered unchecked); a logprob P(yes) under threshold skips the session.
+      Entry.new(key: "broadcast.triage_model",   yaml_path: %w[broadcast triage_model],   type: :string,  default: nil,             expose: %i[env config]),
+      Entry.new(key: "broadcast.triage_host_ref", yaml_path: %w[broadcast triage_host_ref], type: :string, default: nil,            expose: %i[env config]),
+      Entry.new(key: "broadcast.triage_base_url", yaml_path: %w[broadcast triage_base_url], type: :string, default: nil,            expose: %i[env config]),
+      Entry.new(key: "broadcast.triage_parallel", yaml_path: %w[broadcast triage_parallel], type: :integer, default: 4,             expose: %i[env config]),
+      Entry.new(key: "broadcast.triage_deadline", yaml_path: %w[broadcast triage_deadline], type: :float,  default: 20.0,           expose: %i[env config]),
+      Entry.new(key: "broadcast.threshold",      yaml_path: %w[broadcast threshold],      type: :float,   default: 0.5,             expose: %i[env config]),
 
       Entry.new(key: "session.retention_days",        yaml_path: %w[session retention_days],        type: :integer, default: 14,   expose: %i[env config cli]),
       Entry.new(key: "session.max_count",             yaml_path: %w[session max_count],             type: :integer, default: 500,  expose: %i[env config cli]),

data/lib/samagotchi/context_command.rb

@@ -452,22 +452,5 @@ module Samagotchi
       error_line("#{command_name}: #{message}")
       CLI::Exit::FAILED
     end
-
-    # Only a pipe or a file is read, as chi note does: a terminal or a
-    # socket would hang a script.
-    def read_stdin
-      return nil if @stdin.respond_to?(:tty?) && @stdin.tty?
-
-      if @stdin.respond_to?(:stat)
-        stat = @stdin.stat
-        return nil unless stat.pipe? || stat.file?
-      end
-
-      @stdin.read
-    end
-
-    def utf8(text)
-      text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
-    end
   end
 end

data/lib/samagotchi/engine.rb

@@ -2352,11 +2352,10 @@ module Samagotchi
     # @return [String] the answer
     def ask_side_model(request, timeout:, max_tokens:, cancel_controller:)
       target = session_model_recap_target
-      client = IdleClient.new(model: target[:model], base_url: target[:base_url], api_key_env: target[:api_key_env],
-                              timeout: timeout)
+      client = IdleClient.for(target, timeout: timeout)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller)
-      Log.info(:plugins, "ask_model", model: target[:label], answer_model: answer.model, chars: answer.text.length,
+      Log.info(:plugins, "ask_model", model: target.label, answer_model: answer.model, chars: answer.text.length,
                                       ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
       answer.text
     end
@@ -2372,10 +2371,9 @@ module Samagotchi
     # The session's current model as a recap target: its host's OpenAI API
     # (native llama.cpp hosts serve /v1/chat/completions too), key variable
     # and bare model name, as a turn resolves them.
+    # @return [IdleTarget]
     def session_model_recap_target
-      target = @host_registry.resolve(@effective_model_name)
-      { base_url: target.openai_base_url, api_key_env: target.entry.api_key_env,
-        model: target.bare_model, label: @effective_model_name.to_s }
+      IdleTarget.of_model(@host_registry, @effective_model_name)
     end
 
     # Build the idle reminders job. Always created (reminders are opt-in

data/lib/samagotchi/guardrail_wiring.rb

@@ -226,8 +226,13 @@ module Samagotchi
         return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it (non-interactive run).")
       end
 
-      # A plugin tool is asked about by its label, as its row shows it.
-      label = ToolActivity.plugin_label(verdict.call[:name].to_s, registry: @tools_lookup.call)
+      # A plugin tool is asked about by its targets:' label:, else its
+      # label, as its row shows it; a call that acts as another tool (an MCP
+      # tool behind mcp_call) by that tool's label, else (none registered)
+      # by its name (Approval.payload).
+      acts_as = verdict.targets&.acts_as
+      label = verdict.targets&.label ||
+              ToolActivity.plugin_label(acts_as || verdict.call[:name].to_s, registry: @tools_lookup.call)
       # verdict.call is the call that will run (a hook may have replaced it).
       payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call),
                                                       only: (SCRATCH_SCOPES if @scratch))

data/lib/samagotchi/guardrails/approval.rb

@@ -18,7 +18,8 @@ module Samagotchi
 
       # @param verdict [Verdict] an ask, with its targets and context
       # @param label [String, nil] a plugin tool's label ("chrome:
-      #   screenshot"): the question names the tool by it, as its row does;
+      #   screenshot"): the question names the tool by it, as its row does
+      #   (without one, by the tool the call acts as, else its name);
       #   approval[:tool] stays the raw name
       # @param preview [Hash, nil] EditPreview.for(verdict.call) for edit and
       #   write: the card shows its diff, the question text one change line
@@ -37,6 +38,8 @@ module Samagotchi
           kind: KIND,
           approval: {
             tool: targets&.tool || verdict.call[:name].to_s,
+            # The tool the call acts as (an MCP tool behind mcp_call).
+            acts_as: targets&.acts_as,
             label: label,
             command: targets&.command,
             paths: targets && !targets.paths.empty? ? targets.paths : nil,
@@ -126,7 +129,7 @@ module Samagotchi
       #   change: +3 −1                      (edit/write, from the preview)
       def question_text(verdict, label: nil, preview: nil)
         targets = verdict.targets
-        tool = label || targets&.tool || verdict.call[:name].to_s
+        tool = label || targets&.acts_as || targets&.tool || verdict.call[:name].to_s
         what = targets&.command || (targets && targets.paths.join(", "))
         what = Approval.args_text(targets&.args, limit: ARGS_CHARS) if what.to_s.empty?
         lines = ["#{tool}: #{what}"]

data/lib/samagotchi/guardrails/approvals.rb

@@ -90,7 +90,7 @@ module Samagotchi
         return nil unless STORED_SCOPES.include?(scope)
 
         entry = { "scope" => scope, "tool" => verdict.targets&.tool || verdict.call[:name].to_s,
-                  "rule" => verdict.rule, "source" => verdict.source, "created_at" => Time.now.utc.iso8601 }
+                  "acts_as" => verdict.targets&.acts_as, "rule" => verdict.rule, "source" => verdict.source, "created_at" => Time.now.utc.iso8601 }
         case scope
         when "session" then entry.merge!("session_id" => verdict.context&.session_id, "key" => key_for(verdict))
         when "repo"
@@ -110,14 +110,18 @@ module Samagotchi
 
       # tool + the normalized command, or the sorted paths; for a plugin
       # tool with neither (an MCP tool), its arguments, so "this call" is
-      # this call.
+      # this call. A call that acts as another tool keys as
+      # `mcp_call>mcp_github_x`: the real name stays in, so it never reuses
+      # that tool's own approvals (nor they its).
       def self.key_for(verdict)
         t = verdict.targets
         return "#{verdict.call[:name]}:" unless t
-        return "#{t.tool}:#{t.command.to_s.strip.gsub(/\s+/, " ")}" if t.command
-        return "#{t.tool}:#{Approval.args_text(t.args)}" if t.paths.empty?
 
-        "#{t.tool}:#{t.paths.sort.join("\n")}"
+        tool = t.acts_as ? "#{t.tool}>#{t.acts_as}" : t.tool
+        return "#{tool}:#{t.command.to_s.strip.gsub(/\s+/, " ")}" if t.command
+        return "#{tool}:#{Approval.args_text(t.args)}" if t.paths.empty?
+
+        "#{tool}:#{t.paths.sort.join("\n")}"
       end
 
       def self.place_for(verdict)

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -46,6 +46,9 @@ module Samagotchi
       # 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 ask before a memory removal: its paths are in
+      # the config dir, yet a parent may answer it.
+      MEMORY_REMOVE_RULE = "memory-remove"
       # 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})
@@ -94,6 +97,9 @@ module Samagotchi
         return false unless facts.is_a?(Hash)
         return true if PROTECTED_RULES.include?(fetch(facts, :rule).to_s)
         return true if fetch(facts, :source).to_s == ProtectedPaths::SOURCE
+        # A memory's file sits in the config dir, but removing one is the
+        # memory-remove rule's ask, which a parent may answer.
+        return false if fetch(facts, :rule).to_s == MEMORY_REMOVE_RULE
 
         dirs = chi_dirs
         paths = Array(fetch(facts, :paths)).map(&:to_s).reject(&:empty?)

data/lib/samagotchi/guardrails/rules.rb

@@ -9,7 +9,9 @@ module Samagotchi
     # Declarative rules from config.yml's `guardrails:` section (and, later,
     # installed bundles). All the fields a rule gives must match:
     #   tool:    a tool name, a list, or "shell" (execute + task_create);
-    #            a name may be a glob ("mcp_*", "mcp_{git,gh}_*")
+    #            a name may be a glob ("mcp_*", "mcp_{git,gh}_*"); it
+    #            matches the call's name or the tool a plugin tool's call
+    #            acts as (Targets#acts_as: an MCP tool behind mcp_call)
     #   command: a Ruby regex on a shell tool's command
     #   path:    "outside_repo", or a glob on the resolved paths (absolute
     #            or "**/…" globs match the absolute path; others the path
@@ -28,6 +30,7 @@ module Samagotchi
     #   modes:   "strict", "auto" or a list of them: the rule only votes
     #            in those guardrails.mode values (missing = every mode;
     #            a rule from config.yml without it votes in every mode)
+    #   memory:  "remove": a memory_write call with remove: true
     #   skip_read_only: true: a shell command that only reads
     #            (ReadOnlyShell) doesn't match
     # verdict ask|deny, reason, scopes (for an ask; default all).
@@ -38,24 +41,25 @@ module Samagotchi
     class Rules
       class ParseError < StandardError; end
 
-      KEYS = %w[id tool command path git touches rm models modes skip_read_only verdict reason scopes].freeze
-      MATCH_KEYS = %w[tool command path git touches rm].freeze
+      KEYS = %w[id tool command path git touches rm memory models modes skip_read_only verdict reason scopes].freeze
+      MATCH_KEYS = %w[tool command path git touches rm memory].freeze
       VERDICTS = %w[ask deny].freeze
       # guardrails.mode's values.
       MODES = %w[auto strict].freeze
       GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
 
-      Rule = Struct.new(:id, :tools, :command, :path, :git, :touches, :rm, :models, :modes, :skip_read_only, :verdict, :reason,
+      Rule = Struct.new(:id, :tools, :command, :path, :git, :touches, :rm, :memory, :models, :modes, :skip_read_only, :verdict, :reason,
                         :scopes, :source, keyword_init: true) do
         def matches?(targets)
           return false unless targets
           return false unless for_model?(targets.model_name, targets.model_key, -> { targets.small_model? })
-          return false if tools && !tool_matches?(targets.tool)
+          return false if tools && !tool_matches?(targets.tool) && !(targets.acts_as && tool_matches?(targets.acts_as))
           return false if command && !(targets.command && command.match?(targets.command))
           return false if path && !path_matches?(targets)
           return false if git && !targets.git_outside_repo?
           return false if touches && !targets.touches_chi?
           return false if rm && !targets.rm_outside_tmp?
+          return false if memory && !targets.memory_remove?
           return false if skip_read_only && targets.read_only?
 
           true
@@ -128,7 +132,8 @@ module Samagotchi
 
         Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
                  path: path_of(raw["path"], label), git: git_of(raw["git"], label),
-                 touches: touches_of(raw["touches"], label), rm: rm_of(raw["rm"], label), models: models_of(raw["models"], label),
+                 touches: touches_of(raw["touches"], label), rm: rm_of(raw["rm"], label), memory: memory_of(raw["memory"], label),
+                 models: models_of(raw["models"], label),
                  modes: modes_of(raw["modes"], label),
                  skip_read_only: flag_of(raw, "skip_read_only", label), verdict: verdict.to_sym,
                  reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
@@ -185,6 +190,14 @@ module Samagotchi
         value
       end
 
+      # Only "remove" for now.
+      def self.memory_of(value, label)
+        return nil if value.nil?
+        raise ParseError, "#{label}: memory must be remove" unless value == "remove"
+
+        value
+      end
+
       def self.modes_of(value, label)
         return nil if value.nil?