samagotchi 0.12.0 → 0.14.0

data/lib/samagotchi/bundles/check-in/plugin.rb

@@ -15,12 +15,19 @@
 # (a card's actions run while the turn goes on), so the state is behind a
 # Mutex.
 #
+# What /checkin changes (on/off, mode, the threshold) is the session's: it
+# is saved in the bundle's data dir (sessions/<id>.json) and read back
+# when the session comes back (a worker's restart), before its first turn
+# or command. Another session starts from the settings.
+#
 # Settings (config.yml, bundles: check-in:):
 #   after: 50          tool calls in one turn before the first check-in
 #   every: 50          then again every this many more
 #   mode: ask          ask | nudge | notify
 #   message: "..."     what a nudge says; {calls} is the count
 #   ignore_tools: [task_wait, task_get, delegate_result]
+require "fileutils"
+require "json"
 require "securerandom"
 
 class Plugin
@@ -39,6 +46,8 @@ class Plugin
     @message = message.empty? ? DEFAULT_MESSAGE : message
     @ignore = settings.key?("ignore_tools") ? Array(settings["ignore_tools"]).map(&:to_s) : DEFAULT_IGNORE
     @enabled = true
+    @defaults = { "enabled" => @enabled, "mode" => @mode, "after" => @after, "every" => @every }
+    @session = :none # the session whose /checkin state is loaded
     @mutex = Mutex.new
     reset
   end
@@ -69,7 +78,10 @@ class Plugin
 
   def before_turn(ctx)
     close_card(ctx, "The turn ended after #{calls} tool calls.")
-    @mutex.synchronize { reset }
+    @mutex.synchronize do
+      load_session(ctx)
+      reset
+    end
   end
 
   def after_tool_call(event, ctx)
@@ -77,6 +89,7 @@ class Plugin
     return if @ignore.include?(tool)
 
     due = @mutex.synchronize do
+      load_session(ctx)
       @count += 1
       @tools = (@tools + [tool]).last(LAST_TOOLS)
       next nil unless @enabled && @count >= @next_at
@@ -159,18 +172,25 @@ class Plugin
   # --- /checkin --------------------------------------------------------------
 
   def command(args, ctx)
+    @mutex.synchronize { load_session(ctx) }
     case args
     when "" then status
     when "on", "off"
-      @mutex.synchronize { @enabled = args == "on" }
+      @mutex.synchronize do
+        @enabled = args == "on"
+        save_session(ctx)
+      end
       "check-in is #{args} for this session"
     when /\A\d+\z/
-      threshold(Integer(args))
+      threshold(Integer(args), ctx)
     when /\Amode\s+(\S+)\z/
       mode = Regexp.last_match(1)
       return "check-in: unknown mode #{mode} (ask, nudge or notify)" unless MODES.include?(mode)
 
-      @mutex.synchronize { @mode = mode }
+      @mutex.synchronize do
+        @mode = mode
+        save_session(ctx)
+      end
       "check-in mode is #{mode} for this session"
     when "nudge" then nudge(ctx)
     when "later" then later(ctx)
@@ -189,12 +209,13 @@ class Plugin
 
   # For this session: check in at +n+ calls and every +n+ after; a turn
   # already past it is checked on +n+ calls from now.
-  def threshold(n)
+  def threshold(n, ctx)
     return "check-in: the threshold must be at least 1" unless n.positive?
 
     @mutex.synchronize do
       @after = @every = n
       @next_at = n > @count ? n : @count + n
+      save_session(ctx)
     end
     "check-in after #{n} tool calls, then every #{n}, for this session"
   end
@@ -223,6 +244,48 @@ class Plugin
     nil
   end
 
+  # --- the session's /checkin state (under @mutex) ---------------------------
+
+  # The current session's state, when the session isn't the one loaded:
+  # its saved file over the settings.
+  def load_session(ctx)
+    id = ctx.session_id
+    return if id == @session
+
+    @session = id
+    state = @defaults.merge(read_state(ctx, id))
+    @enabled = state["enabled"] == true
+    @mode = MODES.include?(state["mode"]) ? state["mode"] : @defaults["mode"]
+    @after = positive(state["after"]) || @defaults["after"]
+    @every = positive(state["every"]) || @defaults["every"]
+    @next_at = @after if @count.zero?
+  end
+
+  def read_state(ctx, id)
+    return {} unless id
+
+    data = JSON.parse(File.read(state_path(ctx, id)))
+    data.is_a?(Hash) ? data : {}
+  rescue SystemCallError, JSON::ParserError
+    {}
+  end
+
+  # Written aside and renamed: a reader never sees half a file.
+  def save_session(ctx)
+    id = ctx.session_id
+    return unless id
+
+    path = state_path(ctx, id)
+    FileUtils.mkdir_p(File.dirname(path))
+    temp = "#{path}.#{Process.pid}.tmp"
+    File.write(temp, JSON.generate({ "enabled" => @enabled, "mode" => @mode, "after" => @after, "every" => @every }))
+    File.rename(temp, path)
+  rescue SystemCallError => e
+    ctx.log.warn("check_in_state_not_saved", msg: e.message) if ctx.respond_to?(:log)
+  end
+
+  def state_path(ctx, id) = File.join(ctx.data_dir, "sessions", "#{id.to_s.gsub(/[^A-Za-z0-9_.-]+/, "_")}.json")
+
   # --- helpers ---------------------------------------------------------------
 
   def calls = @mutex.synchronize { @count }

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -80,3 +80,22 @@ rules:
     command: '(\.config/samagotchi|samagotchi/config\.yml|samagotchi/hooks|samagotchi/guardrails|memories/\.bundles|\.git/hooks)'
     verdict: ask
     reason: the command names chi's config, hooks, guardrails or git hooks
+
+  # ── answering chi's own questions around chi answer ───────────────────
+  # A parent agent answers a child's approval with chi answer, which holds it
+  # to guardrails.parent_approvals. These shapes go around that: chi --attach
+  # or chi -p with stdin from a pipe, a here-string or a file (a chi after 0.12 treats
+  # those as a parent too, but an older child doesn't), and a POST to the
+  # Bridge's or the web's answer route.
+  - id: chi-answer-piped
+    tool: shell
+    command: '(\|[^;&|\n]*\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b|\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b[^;&|\n]*<)'
+    verdict: ask
+    scopes: [once, session]
+    reason: answers chi's questions from a pipe or a file, around chi answer
+  - id: chi-answer-http
+    tool: shell
+    command: '\b(curl|wget|http|xh)\b[^;&|\n]*/answer\b'
+    verdict: ask
+    scopes: [once, session]
+    reason: posts an answer to a chi session's question directly, around chi answer

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

@@ -1,8 +1,8 @@
 ---
 name: guardrails
-version: 0.2.0
+version: 0.3.0
 scope: system
-description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, writes outside the repo, git hooks), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, writes outside the repo, git hooks, answering chi around chi answer), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed
 # models: in small-models.yml (guardrails.small_models)
 requires_chi: ">= 0.8.1"

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

@@ -1,11 +1,11 @@
 ---
 name: mcp
-version: 0.3.2
+version: 0.4.0
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session, its tools are mcp_<server>_<tool>; /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:61b195a5621ddf57ba69a505aff06d620d6459e836d736205343a251b0fecb71
+  sha256: sha256:009dbb3b754958a6d9edb1e3b828f486aa0ddd09ff5b548f0c576abbfea18807
 requires_chi: ">= 0.8.0"

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

@@ -13,15 +13,18 @@
 #           cwd: ~/scratch      # default: where chi runs
 #           tools: [echo, add]  # optional: only these (globs work)
 #           timeout: 120        # optional: this server's per-call timeout
-#           attach_image_paths: true  # default: a result that is only the path of an
-#                                     # image in the temp dir or cwd attaches it
+#           attach_image_paths: true  # default: an image path in the text, in the
+#                                     # temp dir or cwd, attaches it
 #
 # Image blocks in a result go to the model as images (text: "[image 1:
-# image/png, attached]"); so does a text block that is only the absolute
-# path of an image file under the system temp dir or the server's cwd
-# (chrome-devtools-mcp --slim answers a screenshot that way).
+# image/png, attached]"); so does an image file named in a text block,
+# under the system temp dir or the server's cwd: the block is only its
+# absolute path (chrome-devtools-mcp --slim answers a screenshot that way),
+# or it says one ending in an image extension ("Saved it to /tmp/a.png.").
 # A server that doesn't start, answer or list its tools is skipped with a
-# notice; the rest of chi works. /mcp lists the servers and their tools.
+# 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.
 require "digest"
 require "json"
 require "open3"
@@ -38,6 +41,8 @@ class Plugin
   NAME_CHARS = 48
   # A cached tool list older than this is refreshed in the background.
   CACHE_TTL = 24 * 60 * 60
+  # Restarts of a server that exited, per session.
+  MAX_RESTARTS = 3
   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
@@ -60,9 +65,13 @@ class Plugin
     # @param log [#call] (event, fields) for stderr lines and protocol noise
     # @param on_exit [#call, nil] called once, with the reason, when the
     #   process ends while the client is open
-    def initialize(command, env: {}, cwd: Dir.pwd, log: ->(*) {}, on_exit: nil)
+    # @param on_notification [#call, nil] (method, params) for each
+    #   notification from the server, on the reader thread: it must not
+    #   wait for an answer there
+    def initialize(command, env: {}, cwd: Dir.pwd, log: ->(*) {}, on_exit: nil, on_notification: nil)
       @log = log
       @on_exit = on_exit
+      @on_notification = on_notification
       @mutex = Mutex.new
       @write_mutex = Mutex.new
       @pending = {}
@@ -179,8 +188,11 @@ class Plugin
     def dispatch(message)
       if message.key?("method")
         # A request from the server (ping, roots/list, …): ping is answered,
-        # the rest aren't supported. A notification is logged.
-        return @log.call("server_notification", method: message["method"]) unless message.key?("id")
+        # the rest aren't supported. A notification is logged and handed on.
+        unless message.key?("id")
+          @log.call("server_notification", method: message["method"])
+          return @on_notification&.call(message["method"], message["params"])
+        end
 
         answer = if message["method"] == "ping"
                    { jsonrpc: "2.0", id: message["id"], result: {} }
@@ -227,8 +239,10 @@ class Plugin
   # 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).
+  # +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, keyword_init: true)
+                      :digest, :cached_at, :relist, :relisting, :client, :restarts, keyword_init: true)
 
   def initialize(settings = {})
     @settings = settings
@@ -236,6 +250,8 @@ class Plugin
     @startup_timeout = positive(settings["startup_timeout"]) || STARTUP_TIMEOUT
     @servers = []
     @publish = Mutex.new
+    @relist = Mutex.new
+    @restart = Mutex.new
     # The tools left out so far (a name clash): said once, not at each
     # publish.
     @left_out = []
@@ -255,7 +271,8 @@ class Plugin
     configs = @settings["servers"]
     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: [])
+      server = Server.new(name: name.to_s, config: config.is_a?(Hash) ? config : {}, state: :starting, tools: [],
+                          restarts: 0)
       server.timeout = positive(server.config["timeout"]) || @timeout
       resolve(server, ctx)
       server.service = chi.service(name) { |svc| start(server, svc, ctx) }
@@ -306,16 +323,29 @@ class Plugin
     server.digest = Digest::SHA256.hexdigest(JSON.generate([server.command, server.env.sort, server.cwd]))
   end
 
-  # The service's start: spawn, initialize, list the tools (cancelled with
-  # the turn that waits for it), then cache the list.
+  # The service's start: spawn (#spawn). Its stop closes the server's
+  # current process, a restarted one too.
   def start(server, svc, ctx)
     raise Client::Error, "no command (bundles: mcp: servers: #{server.name}: command: [...])" if server.command.empty?
 
+    svc.on_stop { server.client&.close }
+    spawn(server, ctx)
+  end
+
+  # Spawn the server's process (it is server.client from then on),
+  # initialize, list the tools (cancelled with the turn that waits for
+  # it), then cache the list.
+  # @return [Client]
+  def spawn(server, ctx)
     cancelled = -> { ctx.cancelled? }
-    client = Client.new(server.command, env: server.env, cwd: server.cwd,
-                                        log: ->(event, **fields) { ctx.log.debug("mcp_#{event}", server: server.name, **fields) },
-                                        on_exit: ->(reason) { exited(server, reason, ctx) })
-    svc.on_stop { client.close }
+    client = server.client = Client.new(
+      server.command, env: server.env, cwd: server.cwd,
+                      log: ->(event, **fields) { ctx.log.debug("mcp_#{event}", server: server.name, **fields) },
+                      on_exit: ->(reason) { exited(server, reason, ctx) },
+                      on_notification: lambda { |method, _params|
+                        tools_changed(server, ctx) if method == "notifications/tools/list_changed"
+                      }
+    )
     client.request("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {},
                                    clientInfo: { name: "chi", version: Samagotchi::VERSION } },
                    timeout: @startup_timeout, cancelled: cancelled)
@@ -380,6 +410,46 @@ class Plugin
     nil
   end
 
+  # notifications/tools/list_changed from a running server: list its tools
+  # again (on a thread of its own: the answer comes on the reader thread
+  # that told us), save them and replace the tools for the next turn.
+  # Notices that come together list once more after the one running.
+  def tools_changed(server, ctx)
+    @relist.synchronize do
+      server.relist = true
+      return if server.relisting
+
+      server.relisting = true
+    end
+    Thread.new do
+      relist(server, ctx) while relist_pending?(server)
+    end
+  end
+
+  # Takes the server's pending relist: true once per notice; false (and
+  # the relisting thread ends) when none is left.
+  def relist_pending?(server)
+    @relist.synchronize do
+      pending = server.relist
+      server.relist = false
+      server.relisting = false unless pending
+      pending
+    end
+  end
+
+  def relist(server, ctx)
+    server.service.value # raises once stopped
+    listed = list_tools(server.client, nil)
+    return if listed == server.listed
+
+    server.listed = listed
+    save_cache(server, ctx)
+    ctx.log.info("mcp_tools_changed", server: server.name, tools: listed.size)
+    publish(ctx)
+  rescue StandardError => e
+    ctx.log.warn("mcp_tools_not_relisted", server: server.name, error: e.class.name, msg: e.message)
+  end
+
   # tools/list, every page.
   def list_tools(client, cancelled)
     tools = []
@@ -456,7 +526,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].include?(server.state) }
+        @servers.each { |server| declare(set, server, ctx) if %i[running cached exited].include?(server.state) }
       end
     end
   end
@@ -483,7 +553,13 @@ class Plugin
   def call(server, tool, args, ctx)
     return "Error: MCP server #{server.name} didn't start: #{server.error}" if server.state == :failed
 
-    client = server.state == :cached ? lazy_start(server, ctx) : server.service.value
+    client = case server.state
+             when :cached then lazy_start(server, ctx)
+             when :exited then restart(server, ctx)
+             else
+               server.service.value # raises once stopped
+               server.client
+             end
     return client if client.is_a?(String)
 
     result = client.request("tools/call", { name: tool, arguments: args }, timeout: server.timeout,
@@ -529,6 +605,36 @@ class Plugin
     "Error: MCP server #{server.name} didn't start: #{e.message}"
   end
 
+  # Start a server that exited again, for a call: at most MAX_RESTARTS
+  # times a session. A start that fails or is cancelled leaves it exited
+  # (the next call tries again, while restarts are left).
+  # @return [Client, String] the client, or the call's error text
+  def restart(server, ctx)
+    @restart.synchronize do
+      server.service.value # raises once stopped
+      return server.client if server.state == :running # another call restarted it
+
+      if server.restarts >= MAX_RESTARTS
+        return "Error: MCP server #{server.name} is not running (#{server.error}; restarted #{MAX_RESTARTS} times this session)"
+      end
+
+      server.restarts += 1
+      cached = server.listed
+      server.client&.close
+      begin
+        client = spawn(server, ctx)
+      rescue StandardError => e
+        server.client&.close
+        ctx.log.warn("mcp_server_not_restarted", server: server.name, error: e.class.name, msg: e.message)
+        return "Error: MCP server #{server.name} didn't restart: #{e.message}"
+      end
+      server.state = :running
+      ctx.log.info("mcp_server_restarted", server: server.name, pid: client.pid, restarts: server.restarts)
+      publish(ctx) if server.listed != cached
+      client
+    end
+  end
+
   # The answer's text, and the images to attach: its image blocks, and a
   # text block that is only an image's path (#image_path).
   # @return [Array(String, Array<Hash>)]
@@ -541,11 +647,14 @@ class Plugin
       case block["type"]
       when "text"
         line = block["text"].to_s
-        path = image_path(line, server)
-        next line unless path
+        paths = image_paths(line, server).reject { |path| images.any? { |image| image[:path] == path } }
+        next line if paths.empty?
 
-        images << { path: path, name: File.basename(path) }
-        "#{line}\n[image #{images.size}: #{File.basename(path)}, attached]"
+        notes = paths.map do |path|
+          images << { path: path, name: File.basename(path) }
+          "[image #{images.size}: #{File.basename(path)}, attached]"
+        end
+        [line, *notes].join("\n")
       when "image"
         mime = block["mimeType"] || "unknown type"
         bytes = block["data"].to_s.unpack1("m")
@@ -564,14 +673,31 @@ class Plugin
     [text, images]
   end
 
-  # The path when +text+ is only the absolute path of an image file under
-  # the system temp dir or the server's cwd (a server's text can't pull
-  # in any image on disk), and the server's attach_image_paths isn't off.
-  def image_path(text, server)
-    return nil if server.config["attach_image_paths"] == false
+  # An absolute path ending in an image extension, inside a sentence
+  # ("Saved screenshot to /tmp/shot.png."): no spaces, quotes or brackets.
+  IMAGE_PATH_IN_TEXT = %r{(?<![\w/.~-])/[^\s"'`<>()\[\]{},;]+?\.(?:png|jpe?g|gif|webp)(?![\w/-])}i
+
+  # The images +text+ names, when the server's attach_image_paths isn't
+  # off: the whole text when it is one absolute path (any name), else each
+  # absolute path in it that ends in an image extension. Each must be an
+  # image file (by its bytes) under the system temp dir or the server's
+  # cwd: a server's text can't pull in any image on disk.
+  # @return [Array<String>] real paths, each once
+  def image_paths(text, server)
+    return [] if server.config["attach_image_paths"] == false
+
+    whole = text.strip
+    candidates = if whole.start_with?("/") && !whole.include?("\n") && File.file?(whole)
+                   [whole]
+                 else
+                   text.scan(IMAGE_PATH_IN_TEXT)
+                 end
+    candidates.filter_map { |path| image_path(path, server) }.uniq
+  end
 
-    path = text.strip
-    return nil unless path.start_with?("/") && !path.include?("\n") && File.file?(path)
+  # +path+'s real path when it is an image file under a root, else nil.
+  def image_path(path, server)
+    return nil unless File.file?(path)
 
     real = File.realpath(path)
     roots = [Dir.tmpdir, server.cwd].compact.map { |dir| File.realpath(dir) rescue nil }.compact
@@ -589,14 +715,20 @@ class Plugin
       (head.start_with?("RIFF") && head[8, 4] == "WEBP")
   end
 
-  # The process ended while chi runs: one notice; the calls say so.
+  # The process ended while chi runs: one notice; its next call starts it
+  # again (#restart) while restarts are left.
   def exited(server, reason, ctx)
     return unless server.state == :running
 
     server.state = :exited
     server.error = reason
-    ctx.log.warn("mcp_server_exited", server: server.name, msg: reason)
-    ctx.notify("MCP server #{server.name} stopped: #{reason}; its tools fail until chi restarts", level: :warn)
+    ctx.log.warn("mcp_server_exited", server: server.name, msg: reason, restarts: server.restarts)
+    after = if server.restarts < MAX_RESTARTS
+              "it restarts on its next call"
+            else
+              "it was restarted #{MAX_RESTARTS} times, its tools fail until chi restarts"
+            end
+    ctx.notify("MCP server #{server.name} stopped: #{reason}; #{after}", level: :warn)
   end
 
   def listing
@@ -614,7 +746,7 @@ class Plugin
     when :cached then "cached (not started), #{server.tools.size} tool#{"s" unless server.tools.size == 1}"
     when :running
       count = server.tools.count { |tool| tool["chi_name"] }
-      "running (pid #{server.service.value.pid}), #{count} tool#{"s" unless count == 1}"
+      "running (pid #{server.client.pid}), #{count} tool#{"s" unless count == 1}"
     when :starting then "starting"
     else "#{server.state == :failed ? "failed" : "stopped"}: #{server.error}"
     end

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

@@ -60,7 +60,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 - `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
 - `models:` map of model id or alias → `{profile, vision, sampling, thinking}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: `--thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
-- `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; env `SAMAGOTCHI_GUARDRAILS_ENABLED`), `rules:` (list), `disable:` (list of rule ids, `id` or `bundle:id`, switching off a bundle's or config rule without editing it). A rule takes only `id`, `tool`, `command`, `path`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules load when a session starts: restart the worker/REPL after an edit. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
+- `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
 
 ```yaml
 guardrails:
@@ -122,7 +122,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"`.
 4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it returns one `config: unknown key '…' (did you mean '…'?)` per key chi doesn't read (every config-exposed `Config::ENTRIES` key is known as written, including the section-less `max_tool_output_chars` and `skip_agent_md`; names under `hosts:`/`models:`/`model_aliases:`/`hooks:`/`bundles:`/`memories:` are free-form, host and model entries are checked against `Config::MAP_ENTRY_KEYS`). An empty list means no warning at start.
 5. **Write**: change only the lines you mean to, with the edit tool, so the user's comments and layout stay; `YAML.dump` of the whole hash drops every comment, so rewrite the file only when it has none worth keeping. From Ruby, write atomically with `Samagotchi::AtomicFile.write(path, text)` (a unique temp file renamed over it), never through a fixed `"#{path}.tmp"` that another chi may be writing at the same time.
-6. Nothing else to update: config.yml values are never copied into `ENV`, and every `Config.get` reads the file again when it changed, so the next read (and every worker started after the write) sees the new value with origin `:file`. What a running worker set up at its start (`hosts:`, guardrail rules, bundle settings) waits for its restart. CLI overrides (`--model`, `--recap-model`, …) win over the file until the process exits; a worker gets its spawner's CLI settings through its env (`Config.cli_env`).
+6. Nothing else to update: config.yml values are never copied into `ENV`, and every `Config.get` reads the file again when it changed, so the next read (and every worker started after the write) sees the new value with origin `:file`. What a running worker set up at its start (`hosts:`, bundle settings) waits for its restart; guardrail rules and `model_aliases:` are read again live. CLI overrides (`--model`, `--recap-model`, …) win over the file until the process exits; a worker gets its spawner's CLI settings through its env (`Config.cli_env`).
 
 ## Validations
 
@@ -136,8 +136,8 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
   - must not point to itself (case-insensitive)
   - keys are normalized to downcase on write — `Qwen` and `qwen` collide
 - **Alias target**: non-empty string (model id).
-- **Hosts**: each entry needs `host`, `port` 1-65535, `transport` and `api` optional (a raw `api` must match `transport`), name must match `/\A[a-z0-9][a-z0-9._-]*\z/i`.
-- **Hooks**: each entry must have `path` (relative to `hooks_dir`), `on_error` is `skip` (default) or `log`. Class name must match file basename snake→Pascal.
+- **Hosts**: each entry needs `host` (or `url:`, an http(s) URL with an optional path, replacing `host`/`port`; never both), `port` 1-65535 (default 8080), `enabled: false` skips the entry, `transport` and `api` optional (a raw `api` must match `transport`), name must match `/\A[a-z0-9][a-z0-9._-]*\z/i`.
+- **Hooks**: each entry must have `path` (relative to `hooks_dir`), `on_error` is `skip` (default) or `log`; `required: true` on a `before_tool_call` hook denies the call when the hook raises. Class name must match file basename snake→Pascal.
 - **Scalars via registry**: `Config.coerce` validates `String/Numeric/true/false` per `type: :string/:integer/:float/:bool/:enum`; invalid values warn and fall back to entry `default`.
 - **Keys**: `validate_yaml_sections` flags unknown keys (with a suggestion), a registry section that isn't a mapping, and env/CLI-only keys (`model.profile`).
 
@@ -151,5 +151,5 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 
 - Precedence is `CLI > ENV > file > default` (`Config.resolve`; `Config.get_with_origin` names the layer). `ENV` holds only what the user (or a spawning chi's CLI flags) set, and CLI (`--recap-base-url`) wins over both via `Config.reload!(cli_overrides:)`.
 - `--recap_base_url` (underscore) is rejected as unknown — use `--recap-base-url` (kebab). Same for all registry flags.
-- `model_aliases` require restart or `/model` reload to take effect; document the change.
+- `model_aliases` are read again at each model resolution: an edit applies to the next `--model`, `/model`, new session or delegate, no restart. A running session keeps the model it already resolved.
 - Keep edits minimal: touch only the key you intend to change; preserve `hosts:`/`hooks:`/`guardrails:`/`bundles:` maps. Adding a `bundles: <name>:` entry does not install the bundle (`chi bundle install <name>`).

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.12.0
+version: 0.14.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:93c788fadaf98adeb8946b4a357d2372bd6ebb439042d7cef8dda8fb44187315
-  config_modification_protocol.md: sha256:dddd083d6f419674e6e0cc39118ca9785583a557e4950af1a9b028e52e8a3e0c
+  config_modification_protocol.md: sha256:d0e9d4a84652bf54ec2fd664f61c536637af9decdd22fcd982f52195bf9f5fb4
   memory_guide.md: sha256:81b911b9a015f0924c48162b3dc4b6376309e743765074419a99fab46e480858
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

data/lib/samagotchi/cli/command.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "exit"
+
 module Samagotchi
   module CLI
     # The usage side of a subcommand: its error lines, usage errors (exit 2)
@@ -7,7 +9,6 @@ module Samagotchi
     # #command_name ("chi send"); its usage text is USAGE unless it
     # overrides #usage_text.
     module Command
-      USAGE_EXIT = 2
       HELP_WORDS = %w[-h --help help].freeze
 
       private
@@ -30,7 +31,7 @@ module Samagotchi
         usage = usage_on_error
         error_line("#{command_name}: #{message}#{usage ? "" : " (see #{command_name} --help)"}")
         @stderr.puts(usage) if usage
-        USAGE_EXIT
+        Exit::USAGE
       end
 
       # +argv+ through +flags+ (a Flags), help and usage errors done.

data/lib/samagotchi/cli/exit.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module CLI
+    # chi's exit statuses, one table for every subcommand (docs/cli.md,
+    # docs/sub-agent.md): a script or a parent agent branches on them.
+    module Exit
+      OK = 0
+      # Anything that went wrong at run time: a refusal, a failed turn, a
+      # worker gone, a file that isn't there.
+      FAILED = 1
+      # The command line itself: an unknown flag, a missing argument, an
+      # option the question doesn't offer.
+      USAGE = 2
+      # A question waits for an answer (chi send --wait, chi answer, chi -p).
+      QUESTION = 3
+      # Still running after --timeout.
+      RUNNING = 4
+      # Ctrl-C: what a shell gives a command it interrupted.
+      INTERRUPTED = 130
+    end
+  end
+end