samagotchi 0.11.0 → 0.13.0

data/lib/samagotchi/answer_command.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_manager"
+require_relative "bridge_client"
+require_relative "reply_wait"
+require_relative "parent_report"
+require_relative "guardrails/parent_approvals"
+require_relative "cli/command"
+require_relative "cli/flags"
+require_relative "cli/parent_wait"
+
+module Samagotchi
+  # `chi answer`: answer the question a session's worker waits on (exit 3
+  # from chi send --wait), then wait for what comes next and print it the
+  # same way: the reply (0), the next question (3), still running (4). It is
+  # how a parent agent running chi as a sub-agent answers; the web and
+  # chi --attach answer the same question. See docs/sub-agent.md.
+  #
+  # An approval is the user's to allow: a parent may deny it, and allow it
+  # only "once" when guardrails.parent_approvals (config.yml) says so. It is
+  # checked here and again by the worker, which sees the answer marked as
+  # chi answer's. That guards an honest but eager parent, not a boundary:
+  # the Bridge and the localhost web take answers from any local process.
+  class AnswerCommand
+    include CLI::Command
+    include CLI::ParentWait
+
+    USAGE = <<~TEXT
+      Usage: chi answer ID --question QID (--option N|LABEL)... [--text T] [--timeout S] [--format json]
+             chi answer ID --question QID --dismiss [--timeout S] [--format json]
+        Answers the question session ID waits on (chi send --wait exits 3
+        with it), then waits for what comes next and prints it as chi send
+        --wait does.
+        --question QID  the question's id (chi send --wait prints it); a
+                        question no longer open is not answered
+        --option N|LABEL
+                        an option, by number (1-based) or label; repeat
+                        on a multi-select question
+        --text T        free text, where the question allows it; with an
+                        approval, the reason for a Deny (text alone denies)
+        --dismiss       leave it unanswered: chi does nothing it asked
+                        about and finishes its reply
+        --timeout S     give up waiting after S seconds (exit 4)
+        --format json   one JSON object on stdout (see chi send --help)
+        An approval (a guardrail's ask) can be denied here: deny it, and
+        tell your user; allowing it is the user's. With
+        guardrails.parent_approvals: once, "Allow once" is let through.
+        Exit: 0 answered, 1 failed, refused or the worker is gone, 2
+        usage or an option the question doesn't offer, 3 a question waits,
+        4 still running (--timeout), 130 Ctrl-C.
+    TEXT
+
+    FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|
+      f.value "--question"
+      f.value "--option", key: :options, repeat: true
+      f.value "--text"
+      f.switch "--dismiss"
+      f.value "--timeout"
+      f.value "--format"
+    end
+
+    def initialize(argv, stdout: $stdout, stderr: $stderr, state_dir: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @state_dir = state_dir || Session.default_state_dir
+    end
+
+    private
+
+    def command_name = "chi answer"
+
+    def parse
+      parsed = parse_flags(FLAGS, @argv, options: [])
+      return parsed if parsed.is_a?(Integer)
+
+      options = parsed.options
+      return usage_error("give one session id") unless parsed.args.size == 1
+      return usage_error("--question QID is required (chi send --wait prints it)") if options[:question].to_s.strip.empty?
+      if options[:dismiss]
+        return usage_error("--dismiss takes no --option or --text") if !options[:options].empty? || options[:text]
+      elsif options[:options].empty? && options[:text].nil?
+        return usage_error("nothing to answer with: --option, --text or --dismiss")
+      end
+      return usage_error("--format takes text or json") if options[:format] && !FORMATS.include?(options[:format])
+      if options[:timeout]
+        options[:timeout] = Float(options[:timeout], exception: false)
+        return usage_error("--timeout takes seconds") unless options[:timeout]&.positive?
+      end
+      options.merge(id: parsed.args.first)
+    end
+
+    # Answer, then wait for what comes next.
+    # @return [Integer] the exit status
+    def run_parsed(options)
+      id = resolve(options[:id]) or return 1
+      qid = options[:question].strip
+      session = Session.load(id, state_dir: @state_dir)
+      pending = session.pending_question
+      # Taken before the answer goes in, with the question answered as the
+      # one already reported: the file keeps it until the turn thread
+      # wakes, and it must not come back as exit 3.
+      cursor = ReplyWait.newest_reply(id, state_dir: @state_dir)
+      baseline = ReplyWait.baseline_of(session, question_id: qid)
+
+      if pending && pending[:id].to_s == qid
+        selected = selection(pending, options) or return @selection_status
+        refusal = approval_refusal(pending, selected, id)
+        return failure(refusal) if refusal
+
+        posted = post(id, qid, selected, options)
+        return posted if posted.is_a?(Integer)
+      elsif session.status != Session::STATUS_RUNNING
+        return failure("no question #{qid} waits in #{id[0, 8]}; nothing to answer")
+      else
+        not_open(qid)
+      end
+      # Answered here, or no longer open (answered elsewhere, or a newer
+      # question): what comes next either way.
+      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout])
+    end
+
+    # The labels to send. A number is an option's place (1-based); an
+    # exact label wins over a number.
+    # @return [Array<String>, nil] nil after a usage error
+    def selection(pending, options)
+      offered = Array(pending[:options]).map(&:to_s)
+      labels = options[:options].map do |given|
+        next given if offered.include?(given)
+
+        index = Integer(given, exception: false)
+        next offered[index - 1] if index&.between?(1, offered.size)
+
+        listed = offered.each_with_index.map { |label, i| "#{i + 1}. #{label}" }.join(", ")
+        @selection_status = usage_failure("no option #{given}; the options: #{listed}")
+        return nil
+      end
+      if labels.uniq.size > 1 && !pending[:multi_select]
+        @selection_status = usage_failure("one option only: the question is single-select")
+        return nil
+      end
+      labels.uniq
+    end
+
+    # Why a parent may not give this answer to an approval, or nil
+    # (Guardrails::ParentApprovals, with this process's config.yml). A
+    # Deny, text alone or a dismissal always passes: each one denies. The
+    # worker checks it again with its own config.
+    def approval_refusal(pending, selected, id)
+      offered = Array(pending[:options]).map(&:to_s)
+      indices = selected.map { |label| offered.index(label) }
+      reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: Guardrails::ParentApprovals.setting)
+      reason && Guardrails::ParentApprovals.message(reason)
+    end
+
+    # Post the answer (or the dismissal) to the live worker's Bridge.
+    # @return [Integer, nil] an exit status when it didn't go in; nil to
+    #   wait (it went in, or the question was no longer open: 409)
+    def post(id, qid, selected, options)
+      client = BridgeClient.discover(id, session_dir: Session.session_dir(id, state_dir: @state_dir))
+      return failure(worker_gone(id)) unless client
+
+      reply = nil
+      2.times do
+        reply = if options[:dismiss]
+                  client.dismiss_question(id: qid)
+                else
+                  client.answer(id: qid, selected: selected, freeform: options[:text],
+                                client_id: Guardrails::ParentApprovals::CLIENT_ID)
+                end
+        break unless reply.status == 408
+      end
+
+      case reply.status
+      when 200 then nil
+      when 409 then not_open(qid)
+      when 400 then usage_failure(reply.json&.dig("detail") || "the worker refused the answer")
+      # The worker's own guardrails.parent_approvals refused the allow.
+      when 403 then failure(reply.json&.dig("detail") || "the worker refused the allow: deny it, and tell your user")
+      when 408 then failure("the worker did not take the answer in time; the question is still open: try again")
+      when 404
+        return failure(worker_gone(id)) if reply.json&.dig("error") == "unknown_session"
+
+        cant = options[:dismiss] ? "dismiss a question" : "take an answer"
+        failure(BridgeClient.stale_worker_message(id, cant: cant))
+      else failure("the worker answered #{reply.status}: #{reply.json&.dig("detail") || reply.body}")
+      end
+    rescue Errno::ETIMEDOUT
+      failure("the worker did not take the answer in time; the question is still open: try again")
+    rescue SystemCallError, IOError, SocketError
+      failure(worker_gone(id))
+    end
+
+    # The question was answered elsewhere (the web first), or another one
+    # waits now: said, then what comes next is waited for.
+    # @return [nil]
+    def not_open(qid)
+      error_line("#{command_name}: question #{qid} is no longer open; not answered here, waiting for what comes next")
+      nil
+    end
+
+    def worker_gone(id)
+      "the worker is gone and the question with it; send the task again: chi send --wait -m \"…\" #{id}"
+    end
+
+    # @return [Integer] 1, after the line
+    def failure(line)
+      error_line("#{command_name}: #{line}")
+      1
+    end
+
+    # The Bridge refused the answer itself (an option not offered, two on a
+    # single-select question): a usage error, the question still open.
+    def usage_failure(line)
+      error_line("#{command_name}: #{line}")
+      CLI::Exit::USAGE
+    end
+  end
+end

data/lib/samagotchi/bridge.rb

@@ -18,6 +18,7 @@ require_relative "bridge/sse_writer"
 require_relative "bridge/turn_accumulator"
 require_relative "session"
 require_relative "engine"
+require_relative "guardrails/parent_approvals"
 require_relative "session_commands"
 require_relative "image_store"
 require_relative "log"
@@ -153,7 +154,7 @@ module Samagotchi
       @capture_handle = @engine.subscribe(observer: capture_observer)
       @accumulator_handle = @engine.subscribe(observer: @accumulator)
       # A plugin's ctx.messages mid-turn holds the turn so far (plan O1).
-      @engine.running_turn_messages = -> { @accumulator.current_messages } if @engine.respond_to?(:running_turn_messages=)
+      @engine.running_turn_messages = -> { @accumulator.current_messages }
       @cards_handle = @engine.subscribe(observer: @cards)
       # One a worker that died left is not open.
       @pending_card.clear
@@ -180,7 +181,7 @@ module Samagotchi
       end
       @capture_handle&.unsubscribe
       @accumulator_handle&.unsubscribe
-      @engine.running_turn_messages = nil if @engine.respond_to?(:running_turn_messages=)
+      @engine.running_turn_messages = nil
       @cards_handle&.unsubscribe
       @pending_card_handle&.unsubscribe
       @pending_card&.clear
@@ -217,7 +218,7 @@ module Samagotchi
           continue_offer: @accumulator.continue_offer,
           guardrail_warning: @engine.guardrail_warning,
           plugin_warning: @engine.plugin_warning,
-          init_tasks: @engine.respond_to?(:init_tasks) ? @engine.init_tasks : [],
+          init_tasks: @engine.init_tasks,
           cards: @cards.list,
           commands: command_registry.listing,
           event_seq: seq,
@@ -242,7 +243,7 @@ module Samagotchi
 
     # The Engine's commands: the built-ins and its plugins'.
     def command_registry
-      @engine.respond_to?(:command_registry) ? @engine.command_registry : SessionCommands.builtin_registry
+      @engine.command_registry
     end
 
     # The single shared capture observer: appends every event to the ring.
@@ -496,6 +497,10 @@ module Samagotchi
       qid = fetched(parsed, "id")
       selected = fetched(parsed, "selected")
       freeform = fetched(parsed, "freeform")
+      # chi answer's marker: a parent agent, held to this worker's
+      # guardrails.parent_approvals (QuestionDesk::Refused). Not a boundary:
+      # any local process may post here, with or without it.
+      client_id = fetched(parsed, "client_id")
       if qid.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400, { error: "missing_fields", detail: "id required" }]
       end
@@ -504,11 +509,15 @@ module Samagotchi
       return deadline_passed("answer") if expired?("answer_expired", deadline, sid: session_id, id: qid)
 
       begin
-        result = @engine.answer_question(id: qid, selected: selected, freeform: freeform)
+        result = @engine.answer_question(id: qid, selected: selected, freeform: freeform, client_id: client_id)
         [{}, 200, { status: "answered", session_id: session_id, answer: result }]
       rescue Engine::QuestionNotPending => e
         # Another client answered first, or the question was cancelled.
         [{}, 409, { error: "question_not_pending", detail: e.message }]
+      rescue QuestionDesk::Refused => e
+        Log.info(:bridge, "parent_approval_refused", sid: session_id, id: qid, reason: e.reason)
+        [{}, 403, { error: "parent_approval_refused",
+                    detail: Guardrails::ParentApprovals.message(e.reason) }]
       rescue ArgumentError => e
         [{}, 400, { error: "invalid_answer", detail: e.message }]
       end
@@ -888,6 +897,7 @@ module Samagotchi
       202 => "Accepted",
       204 => "No Content",
       400 => "Bad Request",
+      403 => "Forbidden",
       404 => "Not Found",
       409 => "Conflict",
       500 => "Internal Server Error",

data/lib/samagotchi/bridge_client.rb

@@ -108,10 +108,15 @@ module Samagotchi
 
     # POST /session/:id/answer. 200 = recorded, 409 = another client answered
     # first (or the question is gone), 400 = invalid selection, 408
-    # deadline_passed = read too late and dropped (see DEADLINE_SHARE).
+    # deadline_passed = read too late and dropped (see DEADLINE_SHARE), 403
+    # parent_approval_refused = a parent's allow (client_id cli:answer)
+    # beyond the worker's guardrails.parent_approvals.
+    # @param client_id [String, nil] who answers (chi answer marks its own)
     # @return [Response]
-    def answer(id:, selected:, freeform: nil)
-      post("answer", { id: id, selected: selected, freeform: freeform, deadline: deadline }, read_body: true)
+    def answer(id:, selected:, freeform: nil, client_id: nil)
+      body = { id: id, selected: selected, freeform: freeform, deadline: deadline }
+      body[:client_id] = client_id if client_id
+      post("answer", body, read_body: true)
     end
 
     # POST /session/:id/question/dismiss: leave the question unanswered.

data/lib/samagotchi/bundle_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "cli/flags"
+require_relative "cli/exit"
 require_relative "memory_bundle"
 
 module Samagotchi
@@ -109,7 +110,7 @@ module Samagotchi
       when "build" then build(@argv[1..])
       else
         @stderr.puts "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build"
-        return 2
+        return CLI::Exit::USAGE
       end
     end
 
@@ -124,7 +125,7 @@ module Samagotchi
       force = opts.fetch(:force, false)
       if source.nil? || source.empty?
         @stderr.puts "Usage: chi bundle install <source> [--scope system|project] [--force]"
-        return 2
+        return CLI::Exit::USAGE
       end
       expanded_source = expand_source(source)
       if Samagotchi::MemoryBundle::Profile.shipped_meta?(expanded_source)
@@ -148,7 +149,7 @@ module Samagotchi
       agent = opts[:agent]
       if source.nil? || source.empty?
         @stderr.puts "Usage: chi bundle upgrade <source> [--scope system|project] [--force] [--dry-run]"
-        return 2
+        return CLI::Exit::USAGE
       end
       expanded_source = expand_source(source)
       if Samagotchi::MemoryBundle::Profile.shipped_meta?(expanded_source)
@@ -217,7 +218,11 @@ module Samagotchi
 
     # An upgrade that kept edited files: launch an agent to merge them
     # (--agent, or yes on a terminal), or say how to take the bundle's.
-    # @return [Integer] 0 resolved, 2 kept the edits
+    # An upgrade that kept edited files exits 2, as a usage error does
+    # (scripts already read it so): not CLI::Exit::USAGE by meaning.
+    CONFLICTS_KEPT = 2
+
+    # @return [Integer] 0 resolved, CONFLICTS_KEPT kept the edits
     def upgrade_conflicts(installer, bundle_name, expanded_source, agent)
       @stdout.puts "\n#{installer.conflicts.size} conflict(s) need resolution."
       installer.conflicts.each { |k, _| @stdout.puts "  conflict: #{k}" }
@@ -227,13 +232,13 @@ module Samagotchi
                  ans && ans.strip.downcase.start_with?("y")
                elsif agent.nil?
                  @stdout.puts "Non-interactive terminal: kept your edits in the file(s) above; the rest is upgraded. Re-run with --force to take the bundle's version, or --agent in a TTY to merge."
-                 return 2
+                 return CONFLICTS_KEPT
                else
                  agent
                end
       unless launch
         @stdout.puts "Kept your edits in the file(s) above; the rest is upgraded. chi bundle diff #{bundle_name} FILE shows the base; re-run with --force to take the bundle's version."
-        return 2
+        return CONFLICTS_KEPT
       end
 
       prompt = build_conflict_prompt(bundle_name, installer.conflicts, expanded_source)
@@ -258,7 +263,7 @@ module Samagotchi
       force = opts.fetch(:force, false)
       if bundle_name.nil? || bundle_name.empty?
         @stderr.puts "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
-        return 2
+        return CLI::Exit::USAGE
       end
       data = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).read
       return uninstall_profile(bundle_name, force: force) if Samagotchi::MemoryBundle::Profile.installed_meta?(bundle_name, data)
@@ -355,6 +360,8 @@ module Samagotchi
             exists = File.exist?(hook_path) ? "ok" : "missing"
             @stdout.puts "    #{hk}: event=#{event} on_error=#{on_error} priority=#{prio} [#{exists}]"
           end
+          @stdout.puts "    requires_chi: #{st[:provenance][:requires_chi]}" if st[:hooks_requires_failure]
+          @stdout.puts "    not loaded: #{st[:hooks_requires_failure]}" if st[:hooks_requires_failure]
         end
         if (plugin = st[:plugin])
           note = plugin[:state] == "modified" ? " (edited after install: not loaded; reinstall the bundle)" : ""
@@ -379,6 +386,7 @@ module Samagotchi
           hook_info = hooks_count > 0 ? " hooks=#{hooks_count}" : ""
           plugin = st[:plugin]
           mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
+          mods += 1 if st[:hooks_requires_failure]
           plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
           includes = st[:provenance][:includes]
           includes_info = includes ? " includes=#{includes.join(",")}" : ""
@@ -393,7 +401,7 @@ module Samagotchi
       bname = args[0]
       file_arg = args[1]
       if bname.nil? || bname.empty?
-        @stderr.puts "Usage: chi bundle diff <bundle> [file]"; return 2
+        @stderr.puts "Usage: chi bundle diff <bundle> [file]"; return CLI::Exit::USAGE
       end
       prov = Samagotchi::MemoryBundle::Provenance.new(name: bname)
       data = prov.read
@@ -534,7 +542,7 @@ module Samagotchi
       # Validate scope if given
       if scope && !%w[system project].include?(scope.to_s.strip.downcase)
         @stderr.puts "Invalid scope '#{scope}', expected system or project"
-        return 2
+        return CLI::Exit::USAGE
       end
       begin
         builder = Samagotchi::MemoryBundle::Builder.new(
@@ -573,7 +581,7 @@ module Samagotchi
       end
       if parsed.error
         @stderr.puts "Unknown bundle #{sub} flag: #{parsed.error.arg}"
-        return 2
+        return CLI::Exit::USAGE
       end
       parsed
     end

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/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.11.0
+version: 0.13.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