samagotchi 0.17.0 → 0.18.1

data/docs/sub-agent.md

@@ -34,9 +34,10 @@ Exit codes, both commands:
 |---|---|---|
 | 0 | `answered` | `text` is chi's reply |
 | 0 | `command` | (`chi send`) the message was a session command (`/model x`): it ran as one, no reply comes |
+| 0 | `not_continued` | (`chi answer`) a Stop answered the step-limit question; the turn's work so far stays |
 | 3 | `question` | chi waits for an answer: `question`, `answer_with` |
 | 4 | `running` | `--timeout` passed; the turn goes on, wait again |
-| 1 | `failed`, `canceled`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened |
+| 1 | `failed`, `canceled`, `limit`, `no_answer`, `error`, `worker_gone`, `stopped` | `detail` says what happened (`limit`: the turn ran out of steps and nobody can be asked, e.g. an older worker; `chi send ID -m '/continue yes'` continues it) |
 | 2 | (no JSON) | usage error, or an option the question doesn't offer |
 | 130 | `running` | Ctrl-C; the turn goes on |
 
@@ -49,8 +50,33 @@ With `--format json` stdout is one JSON object (see
   "allow_freeform":false},"answer_with":"chi answer 297da360-… --question 3f1c… --option N"}
 ```
 
-`kind` is `question` (the model's), `hook`, or `approval`, which adds the tool,
-command, folder, rule and reason.
+`kind` is `question` (the model's), `hook`, `approval`, which adds the tool,
+command, folder, rule and reason, or `continue`, the step-limit question below.
+
+## The step limit
+
+A turn that runs out of steps (`turn.max_iterations`, default 100) before it
+answers waits as a question of kind `continue` (`"limit": 100`, options
+`Continue` and `Stop`). `answer_with` continues it:
+`chi answer ID --question QID --option Continue`, and the continued turn's
+reply (or its next question) comes back on that same wait. To stop it:
+`--option Stop`, with `--text "why"` for the model (Continue takes no text);
+that wait ends with `status: not_continued`, exit 0, and the turn's work so far
+stays in the session. A message instead (`chi send ID -m "…"`) drops the
+question and starts a new turn. It can't be dismissed.
+
+A parent may Continue by default: Continue grants no permission (every tool
+call still meets the guardrails), it only spends time and tokens. With
+`turn.parent_continue: false` in chi's config.yml (config.yml only, no
+environment variable) a parent may only Stop: `chi answer` and the worker
+refuse a Continue (exit 1, `a parent agent may only stop this turn here`), and
+the user continues it from the web or the terminal.
+
+A chi parent's `delegate_result` gets a child's step-limit question back as a
+`question` with these commands, for its model to decide: continue it (the
+`chi answer` command, through `execute`), send a narrower follow-up with
+`delegate session:` (which drops the question), or report back. It isn't
+relayed to the parent's user the way approvals are.
 
 ## Approvals
 
@@ -75,6 +101,10 @@ variable), "Allow once" goes through; the wider scopes never do,
 and neither does any allow on chi's own config, hooks or guardrail rules. See
 [Guardrails](guardrails.md#approvals-from-a-parent-agent).
 
+Start a child in the folder it should change (`chi send --new --dir PATH`):
+writes and mutating git outside its own repo ask (`write-outside-repo`,
+`git-outside-repo`), which a parent can only deny.
+
 An answer typed into `chi --attach` or the REPL counts as a parent's too when
 stdin isn't a terminal or an agent marker (`CLAUDECODE`, `AI_AGENT`,
 `CODEX_THREAD_ID`, `SAMAGOTCHI_PARENT_SESSION`) is set.
@@ -96,7 +126,11 @@ answers from any local process.
   `chi answer` then exits 1 and says to send the task again
   (`chi send --wait -m "…" ID`); a wait ends with `worker_gone` (exit 1).
 - A follow-up (`chi send --wait -m "…" ID`) to a session waiting for an answer
-  isn't sent: it exits 1 with the `chi answer` command for the question.
+  isn't sent: it exits 1 with the `chi answer` command for the question. The
+  step-limit question is the exception: it waits between turns, so a message
+  goes in, drops it and starts a new turn.
+- `chi send --wait ID` with no message waits past a question already reported
+  (the step-limit question too), until someone answers it.
 - An answer to a question that is no longer open (you answered it in the web
   first) isn't sent; `chi answer` says so and waits for what comes next.
 - `chi send --wait` and `chi answer` don't read stdin unless it's a pipe or a
@@ -130,6 +164,10 @@ Start a task: `chi send --new --wait --format json --timeout 500 -m "<task>"`
   `chi answer`, a piped `chi --attach` or chi's web API.
 - `status: running` (exit 4): still working. Wait again:
   `chi send --wait --format json --timeout 500 <session_id>`.
+- `question.kind: continue`: chi ran out of steps before it answered. If it is
+  getting somewhere, continue it (`answer_with`, `--option Continue`); if not,
+  stop it (`--option Stop --text "why"`, exit 0, status `not_continued`) or send
+  a narrower follow-up instead. Ask your user when unsure.
 - Anything else (exit 1): report `detail` to your user. `chi --attach <session_id>`
   shows the session.
 

data/lib/samagotchi/answer_command.rb

@@ -6,6 +6,7 @@ require_relative "bridge_client"
 require_relative "reply_wait"
 require_relative "parent_report"
 require_relative "guardrails/parent_approvals"
+require_relative "guardrails/parent_continue"
 require_relative "cli/command"
 require_relative "cli/flags"
 require_relative "cli/parent_wait"
@@ -46,6 +47,9 @@ module Samagotchi
         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.
+        A step-limit question (kind continue): --option Continue, or
+        --option Stop [--text WHY] (exit 0, status not_continued); it
+        can't be dismissed.
         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.
@@ -105,8 +109,10 @@ module Samagotchi
       baseline = ReplyWait.baseline_of(session, question_id: qid)
 
       if pending && pending[:id].to_s == qid
+        return failure(not_dismissable(pending)) if options[:dismiss] && ParentReport.continue?(pending)
+
         selected = selection(pending, options) or return @selection_status
-        refusal = approval_refusal(pending, selected, id)
+        refusal = approval_refusal(pending, selected, id) || continue_refusal(pending, selected)
         return failure(refusal) if refusal
 
         posted = post(id, qid, selected, options)
@@ -154,6 +160,18 @@ module Samagotchi
       reason && Guardrails::ParentApprovals.message(reason)
     end
 
+    # Why a parent may not answer Continue (turn.parent_continue: false in
+    # this process's config.yml), or nil; the worker checks it again.
+    def continue_refusal(pending, selected)
+      Guardrails::ParentContinue.refusal(pending, selected) && Guardrails::ParentContinue.message
+    end
+
+    # A step-limit question can't be left unanswered: the turn waits on it.
+    def not_dismissable(pending)
+      "the step-limit question can't be dismissed: answer #{Array(pending[:options]).join(' or ')} " \
+        "(--option Stop --text WHY stops it)"
+    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)
@@ -174,7 +192,10 @@ module Samagotchi
 
       case reply.status
       when 200 then nil
-      when 409 then not_open(qid)
+      when 409
+        return failure(reply.json&.dig("detail").to_s) if reply.json&.dig("error") == "not_dismissable"
+
+        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")

data/lib/samagotchi/answer_tail.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "context_note"
+require_relative "output_formatter"
+require_relative "steer"
+require_relative "turn_note"
+
+module Samagotchi
+  # "The last answer a UI shows": the newest message the web's history
+  # shows as an assistant message. One rule for the worker's Bridge (`/tail`,
+  # Engine#last_answer_message) and the web's disk path, so the two can't
+  # drift. Any change to what the web shows as an answer goes through here.
+  module AnswerTail
+    module_function
+
+    # @param messages [Array<Hash>] a session's messages (symbol keys from
+    #   disk or the Engine, string keys from a Bridge snapshot)
+    # @param turn_id [String, nil] that turn's answer: the last one between
+    #   the prompt carrying this turn id and the next prompt (a queued turn's
+    #   page re-reads after the next turn ran). An unknown or missing id:
+    #   the newest answer.
+    # @return [Hash, nil] the raw message (not a copy), or nil
+    def find(messages, turn_id: nil)
+      list = Array(messages)
+      list = turn_slice(list, turn_id.to_s) || list unless turn_id.to_s.empty?
+      list.reverse_each { |m| return m if answer?(m) }
+      nil
+    end
+
+    # The messages of the turn whose prompt carries +turn_id+, from its
+    # prompt up to the next prompt (merged input and steers stay in it), or
+    # nil when no prompt carries it.
+    def turn_slice(list, turn_id)
+      start = list.rindex { |m| Steer.turn_prompt?(m) && (m[:turn_id] || m["turn_id"]).to_s == turn_id }
+      return nil unless start
+
+      stop = list.each_index.find { |i| i > start && Steer.turn_prompt?(list[i]) } || list.size
+      list[start...stop]
+    end
+
+    # Shown as an assistant message: role assistant or model, not a context
+    # note, a steer or a no-answer turn's marker, and some text left once the
+    # wire-format markup is stripped (a tool-call-only step has none).
+    def answer?(message)
+      return false unless message.is_a?(Hash)
+      return false if ContextNote.note?(message) || Steer.steer?(message) || TurnNote.empty_answer(message)
+      return false unless %w[assistant model].include?((message[:role] || message["role"]).to_s)
+
+      !OutputFormatter.strip_markup((message[:content] || message["content"]).to_s).empty?
+    end
+  end
+end

data/lib/samagotchi/bridge.rb

@@ -209,8 +209,11 @@ module Samagotchi
     # last cards and between-turns notices (CardStore#list), the session's commands (Commands::Registry#listing:
     # what an attached TUI routes and completes, the web's autocomplete), and the event_seq it all covers.
     # Taken with the log held, so no event is half-applied.
-    # @return [Hash] {messages:, current_turn:, queued:, recap:, saved_recap:, continue_offer:, guardrail_warning:,
-    #   plugin_warning:, init_tasks:, cards:, commands:, event_seq:, event_id:}
+    # The pending question at the top level too: one asked between turns
+    # (the step-limit question) belongs to no turn, so the accumulator
+    # doesn't keep it.
+    # @return [Hash] {messages:, current_turn:, queued:, recap:, saved_recap:, continue_offer:, pending_question:,
+    #   guardrail_warning:, plugin_warning:, init_tasks:, cards:, commands:, event_seq:, event_id:}
     def snapshot
       @engine.synchronize_events do
         seq = @engine.event_count
@@ -221,6 +224,7 @@ module Samagotchi
           recap: @accumulator.recap,
           saved_recap: @engine.saved_recap,
           continue_offer: @accumulator.continue_offer,
+          pending_question: @engine.pending_question,
           guardrail_warning: @engine.guardrail_warning,
           plugin_warning: @engine.plugin_warning,
           init_tasks: @engine.init_tasks,
@@ -244,12 +248,30 @@ module Samagotchi
       end
     end
 
+    # What the page re-reads at a turn's end and when a card arrives: the
+    # session state, the last answer (Engine#last_answer_message: one
+    # message, not the conversation) and the cards, as one step of the event
+    # log (one event_seq). Light whatever the session's length: GET tail.
+    # @return [Hash] {session_id:, session_state_snapshot:, answer:, cards:, event_seq:, event_id:}
+    # +turn_id+: that turn's answer, not the newest (Engine#last_answer_message).
+    def tail_frame(turn_id: nil)
+      @engine.synchronize_events do
+        seq = @engine.event_count
+        state = @engine.session_state_snapshot.merge(event_seq: seq, event_id: event_id(seq))
+        { session_id: @session_id, session_state_snapshot: state, answer: @engine.last_answer_message(turn_id: turn_id),
+          cards: @cards.list, event_seq: seq, event_id: event_id(seq) }
+      end
+    end
+
     # The worker's own way in for a session command that came as a message
     # (its first prompt, an input file): queued and announced as a POST
     # /command's is (#handle_command).
     # @return [String] its command_id
-    def queue_command(line, client_id: nil)
+    def queue_command(line, client_id: nil, card: false)
       command = { command_id: SecureRandom.uuid, client_id: client_id, line: line.to_s.strip }
+      # A card's action (the step-limit question's answer): the UIs leave
+      # its line out.
+      command[:card] = true if card
       @engine.synchronize_events { queue_command_locked(command) }
       command[:command_id]
     end
@@ -347,7 +369,7 @@ module Samagotchi
                                     client_id: stream_client_id(request[:query]))
           break # SSE owns the connection until the client disconnects.
         else
-          payload, status, body = dispatch(route.first, route.last, request[:body])
+          payload, status, body = dispatch(route.first, route.last, request[:body], request[:query])
           write_json(io, status, payload, body)
         end
 
@@ -446,7 +468,8 @@ module Samagotchi
       %w[POST relay/status] => :handle_relay_status,
       %w[GET state] => :handle_state,
       %w[GET stats] => :handle_stats,
-      %w[GET snapshot] => :handle_snapshot
+      %w[GET snapshot] => :handle_snapshot,
+      %w[GET tail] => :handle_tail
     }.freeze
     ROUTE_PATH = %r|\A/session/([^/]+)/(.+)\z|u
 
@@ -462,8 +485,10 @@ module Samagotchi
     # #own_session?), and a handler that raises answers 500 bridge_error,
     # logged (the connection thread doesn't report).
     # @return [Array(Hash, Integer, Hash)] headers, status, body
-    def dispatch(handler, session_id, body)
+    # Only GET tail takes the request's +query+.
+    def dispatch(handler, session_id, body, query = nil)
       return [{}, 404, { error: "unknown_session" }] unless own_session?(session_id)
+      return handle_tail(session_id, body, query) if handler == :handle_tail
 
       send(handler, session_id, body)
     rescue StandardError => e
@@ -533,7 +558,7 @@ module Samagotchi
         [{}, 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",
+        [{}, 403, { error: e.reason == :stop_only ? "parent_continue_refused" : "parent_approval_refused",
                     detail: Guardrails::ParentApprovals.message(e.reason) }]
       rescue ArgumentError => e
         [{}, 400, { error: "invalid_answer", detail: e.message }]
@@ -589,7 +614,12 @@ module Samagotchi
       return BAD_DEADLINE unless deadline_valid?(deadline)
       return deadline_passed("dismissal") if expired?("dismiss_expired", deadline, sid: session_id, id: qid)
 
-      dismissed = @engine.cancel_question("dismissed", id: qid)
+      begin
+        dismissed = @engine.cancel_question("dismissed", id: qid)
+      rescue QuestionDesk::NotDismissable => e
+        # A step-limit question: its answer is Continue or Stop.
+        return [{}, 409, { error: "not_dismissable", detail: e.message }]
+      end
       return [{}, 409, { error: "question_not_pending", detail: "no pending question #{qid}" }] unless dismissed
 
       [{}, 200, { status: "dismissed", id: qid, session_id: @session_id }]
@@ -764,6 +794,17 @@ module Samagotchi
       [{}, 200, snapshot_frame]
     end
 
+    # The page's light re-read (#tail_frame): no message list. `?turn_id=`:
+    # that turn's answer (a queued turn's page re-reads late). The one
+    # handler that gets the query (#dispatch); an older worker's route
+    # ignores it and sends the newest answer.
+    def handle_tail(session_id, _body = nil, query = nil)
+      turn_id = query && URI.decode_www_form(query).to_h["turn_id"].to_s
+      [{}, 200, tail_frame(turn_id: turn_id.to_s.empty? ? nil : turn_id)]
+    rescue ArgumentError
+      [{}, 200, tail_frame]
+    end
+
     # The stream cursor for +seq+ in this worker.
     def event_id(seq)
       EventId.format(seq.to_i, @epoch)

data/lib/samagotchi/bridge_client.rb

@@ -210,17 +210,32 @@ module Samagotchi
     # GET /session/:id/<path> as JSON.
     # @return [Hash, nil] the parsed body, or nil unless the Bridge answered 200
     def get_json(path)
+      status, body = get(path)
+      status == 200 ? body : nil
+    end
+
+    # GET /session/:id/<path>, telling a refusal apart from no answer: an
+    # older worker's 404 for a route it lacks from a refused connect, a
+    # timeout or a 500.
+    # @return [Array(Integer, Object)] the status and the parsed JSON body
+    #   (nil when it isn't JSON); [nil, nil] when no reply came
+    def get(path)
       sock = TCPSocket.new(@host, @port)
       sock.write("GET /session/#{@session_id}/#{path} HTTP/1.1\r\nHost: #{@host}:#{@port}\r\nConnection: close\r\n\r\n")
       response = read_reply(sock, path)
       sock.close rescue nil
       # A 500 whose text has "200" in it is not a 200.
-      return nil unless response && response[STATUS_LINE, 1] == "200"
+      status = response && response[STATUS_LINE, 1]
+      return [nil, nil] unless status
 
       body = response.split("\r\n\r\n", 2)[1] || ""
-      JSON.parse(body)
+      [status.to_i, begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end]
     rescue StandardError
-      nil
+      [nil, nil]
     end
 
     # Monotonic SSE cursor of the live Engine, from GET /session/:id/state.

data/lib/samagotchi/bundle_command.rb

@@ -10,7 +10,7 @@ module Samagotchi
   # subcommands have their own flags).
   class BundleCommand
     USAGE = <<~TEXT
-      Usage: chi bundle <install|upgrade|uninstall|status|diff|list|build> [options]
+      Usage: chi bundle <install|upgrade|uninstall|status|diff|list|build|trash> [options]
 
         install <source> [--scope system|project] [--force]
           Install a memory bundle from a directory, zip, tar archive, or git URL.
@@ -37,6 +37,10 @@ module Samagotchi
           Build local memories and installed hooks (and plugin) into a shareable bundle (dir or zip).
           --scope selects source dir (default: system). --out inferred from extension; default <name>.zip.
           FILES... optional allowlist of *.md basenames to include (default: all but installed bundles' ones).
+
+        trash [--empty] [--dry-run] [--older-than DAYS]
+          List bundle trash (moved files from uninstalls/upgrades).
+          --empty deletes all trash folders. --older-than DAYS keeps only recent ones.
     TEXT
 
     # Each subcommand's --help (and only --help: -h and help are taken as
@@ -64,6 +68,7 @@ module Samagotchi
           chi bundle build --scope project --name my-bundle --version 1.0.0 --out bundle.zip
           chi bundle build --scope system --out ./my-bundle/ identity.md work.md
     TEXT
+    TRASH_HELP = "Usage: chi bundle trash [--empty] [--dry-run] [--older-than DAYS]"
 
     # The subcommands' flags: --help only; a word not starting with -- is
     # a positional (install's source, -h included). --scope takes whatever
@@ -83,6 +88,11 @@ module Samagotchi
     BUILD_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/, dash_values: false) do |f|
       %w[--scope --name --version --description --out].each { |name| f.value name }
     end
+    TRASH_FLAGS = CLI::Flags.new(help: %w[--help], flag_pattern: /\A--/) do |f|
+      f.switch "--empty"
+      f.switch "--dry-run"
+      f.value "--older-than"
+    end
 
     # @param argv [Array<String>] the arguments after "bundle"
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr)
@@ -108,8 +118,9 @@ module Samagotchi
       when "diff" then diff(@argv[1..])
       when "list" then list
       when "build" then build(@argv[1..])
+      when "trash" then trash(@argv[1..])
       else
-        @stderr.puts "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build"
+        @stderr.puts "Unknown bundle subcommand: #{sub}. Use: install, upgrade, uninstall, status, diff, list, build, trash"
         return CLI::Exit::USAGE
       end
     end
@@ -579,6 +590,101 @@ module Samagotchi
       end
     end
 
+    def trash(rest)
+      parsed = parse_flags(TRASH_FLAGS, rest, "trash", help: TRASH_HELP)
+      return parsed if parsed.is_a?(Integer)
+
+      opts = parsed.options
+      empty = opts.fetch(:empty, false)
+      dry_run = opts.fetch(:dry_run, false)
+      older_than = opts[:older_than]
+
+      # --older-than and --dry-run without --empty are a usage error
+      if (older_than || dry_run) && !empty
+        @stderr.puts "Usage: chi bundle trash [--empty] [--dry-run] [--older-than DAYS]"
+        return CLI::Exit::USAGE
+      end
+
+      # Validate older_than if given
+      if older_than
+        if older_than.to_s.match?(/\A\d+\z/) && older_than.to_i > 0
+          older_than = older_than.to_i
+        else
+          @stderr.puts "Usage: chi bundle trash [--empty] [--dry-run] [--older-than DAYS]"
+          return CLI::Exit::USAGE
+        end
+      end
+
+      if empty
+        do_empty(older_than_days: older_than, dry_run: dry_run)
+      else
+        do_list
+      end
+    end
+
+    def do_list
+      entries = Samagotchi::MemoryBundle::Trash.entries
+      if entries.empty?
+        @stdout.puts "The bundle trash is empty."
+        return 0
+      end
+
+      entries.each do |e|
+        @stdout.puts "  #{e.name}  #{e.files} file#{'s' unless e.files == 1}  #{format_bytes(e.bytes)}  #{format_age(e.time)}"
+      end
+      @stdout.puts "\nEmpty it with: chi bundle trash --empty [--older-than DAYS]"
+      0
+    end
+
+    def do_empty(older_than_days:, dry_run:)
+      entries = Samagotchi::MemoryBundle::Trash.empty!(
+        older_than_days: older_than_days,
+        dry_run: dry_run,
+      )
+      if entries.empty?
+        @stdout.puts "The bundle trash is empty."
+        return 0
+      end
+
+      total_files = entries.sum(&:files)
+      if dry_run
+        entries.each do |e|
+          @stdout.puts "Would delete: #{e.name} (#{e.files} file#{'s' unless e.files == 1}, #{format_bytes(e.bytes)})"
+        end
+        @stdout.puts "\n(dry-run: #{entries.size} folder#{'s' unless entries.size == 1}, #{total_files} file#{'s' unless total_files == 1})"
+      else
+        @stdout.puts "Deleted #{entries.size} folder#{'s' unless entries.size == 1} (#{total_files} file#{'s' unless total_files == 1}) from the trash."
+      end
+      0
+    end
+
+    # Format bytes as human-readable (B, KB, MB with one decimal)
+    def format_bytes(bytes)
+      return "0 B" if bytes == 0
+      if bytes < 1024
+        "#{bytes} B"
+      elsif bytes < 1_048_576
+        "#{(bytes / 1024.0).round(1)} KB"
+      else
+        "#{(bytes / 1_048_576.0).round(1)} MB"
+      end
+    end
+
+    # Format age as "just now", "N minutes ago", "N hours ago", "N days ago"
+    def format_age(time)
+      now = Time.now
+      diff = now - time
+      if diff < 60
+        "just now"
+      elsif diff < 3600
+        "#{(diff / 60).to_i} minutes ago"
+      elsif diff < 86_400
+        "#{(diff / 3600).to_i} hours ago"
+      else
+        "#{(diff / 86_400).to_i} days ago"
+      end
+    end
+
     # +rest+ through +flags+, stopping at the first --help or error.
     #
     # @return [CLI::Flags::Result, Integer] the result, or the exit status

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

@@ -4,7 +4,8 @@
 # earlier or `git -C` variants can get past them.
 #
 # Fields: id, tool (a name, a list, or shell = execute + task_create),
-# command (Ruby regex), path (outside_repo or a glob), verdict (ask|deny),
+# command (Ruby regex), path (outside_repo or a glob), git (outside_repo:
+# a shell call runs commit/add/reset/… in another checkout), verdict (ask|deny),
 # reason, scopes (for an ask: once, session, repo, rule; default all).
 # [^;&|\n]* keeps a match inside one command of a chain; the git rules match
 # the subcommand after optional global options (git -C dir push).
@@ -62,12 +63,26 @@ rules:
     verdict: ask
     reason: runs decoded text as a script
 
-  # ── files outside the repo, and git hooks ──────────────────────────────
+  # ── work outside this session's repo, and git hooks ───────────────────
+  # outside_repo: not in the session's repo (its folder outside a repo);
+  # tmp dirs and memory files don't count.
   - id: write-outside-repo
     tool: [write, edit]
     path: outside_repo
     verdict: ask
-    reason: writes outside the repository
+    reason: writes outside this session's repo
+  # cd/git -C into another checkout, then commit, add, reset, checkout,
+  # switch, rebase, merge, push, stash, rm, mv, cherry-pick, revert, pull,
+  # restore or am. Read-only git (status, log, diff) and tests there run.
+  # "This call in this repo" would never match again (the command holds
+  # the commit message), so it isn't offered: "rule in this repo" is the
+  # always-for-here answer.
+  - id: git-outside-repo
+    tool: shell
+    git: outside_repo
+    verdict: ask
+    scopes: [once, session, rule]
+    reason: runs git that changes another checkout, outside this session's repo
   - id: git-hooks-write
     tool: [write, edit]
     path: '**/.git/hooks/**'

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

@@ -1,10 +1,10 @@
 ---
 name: guardrails
-version: 0.3.0
+version: 0.4.0
 scope: system
-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
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, writes and git in another checkout outside the session's 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"
+# models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0
+requires_chi: ">= 0.18.0"
 files:
   guardrails.md: sha256:04207fd1738aeeeef3b7a8053fc57597565bddd7862f01acaba784419cbd909b

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; 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.
+- `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`, `git`, `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`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `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:

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.17.0
+version: 0.18.1
 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:69bc0ec091fdaeedf6e3aa7365275461fe3eba32b2dedc9cf45044176c356af5
-  config_modification_protocol.md: sha256:d0e9d4a84652bf54ec2fd664f61c536637af9decdd22fcd982f52195bf9f5fb4
+  config_modification_protocol.md: sha256:8d8921854e616d840b393cdda6fd911b7d5e8172501bb8293c01f734121ccc21
   memory_guide.md: sha256:e535e31fcf29b4b32c270042851ecdd5f412ef2e3c56b0076963e3e1f1a08ef8
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561