samagotchi 0.59.0 → 0.61.0

data/lib/samagotchi/answer_refs.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "log"
+require_relative "ref"
+
+module Samagotchi
+  # One ref on the answer: the text it stands for (+match+, what the page
+  # pairs it with) and the Ref itself. +to_h+ is the stored and sent shape,
+  # {match:, kind:, target:, label:, actions:}.
+  AnswerRef = Data.define(:match, :ref) do
+    # @raise [ArgumentError] an empty match, one over MAX_MATCH, or a ref
+    #   that isn't a Ref
+    def initialize(match:, ref:)
+      match = match.to_s.strip
+      raise ArgumentError, "a ref needs a match (the text it stands for)" if match.empty?
+      raise ArgumentError, "a ref's match is at most #{AnswerRef::MAX_MATCH} characters" if match.length > AnswerRef::MAX_MATCH
+      raise ArgumentError, "not a Ref" unless ref.is_a?(Ref)
+
+      super
+    end
+
+    def to_h = { match: match, **ref.to_h }
+  end
+
+  class AnswerRef
+    MAX_MATCH = 500
+
+    # A hook's {match:, kind:, target:, label:, actions:}, or a stored
+    # entry (String or Symbol keys, nested ones too). A file ref's relative
+    # path is resolved against +cwd+, so the stored path is absolute; with
+    # no +cwd+ it is refused. An absolute path stays as given.
+    # @raise [ArgumentError] anything invalid
+    def self.from(value, cwd: nil)
+      raise ArgumentError, "a ref is a Hash {match:, kind:, target:, label:, actions:}" unless value.is_a?(Hash)
+
+      value = value.transform_keys(&:to_sym)
+      ref = Ref.new(kind: value[:kind], target: value[:target], label: value[:label], actions: value[:actions] || [])
+      new(match: value[:match], ref: absolute(ref, cwd))
+    end
+
+    def self.absolute(ref, cwd)
+      return ref unless ref.kind == Ref::FILE
+
+      path = ref.target[:path]
+      return ref if File.absolute_path?(path)
+      raise ArgumentError, "relative path, no session folder" if cwd.to_s.empty?
+
+      # absolute_path, not expand_path: a leading ~ is a name, never a home.
+      Ref.new(kind: ref.kind, target: ref.target.merge(path: File.absolute_path(path, cwd.to_s)), label: ref.label,
+              actions: ref.actions)
+    end
+    private_class_method :absolute
+  end
+
+  # The refs after_turn hooks attach to a turn's answer (event[:refs]),
+  # kept as `display_refs` on the answer's model message next to its
+  # `display` (AnswerDisplay). Display only, like `display`: the model
+  # never sees them (AnswerDisplay::DISPLAY_ONLY), and a UI pairs each with
+  # its +match+ in the shown answer (or drops it).
+  #
+  # The target is AnswerDisplay's: the stored conversation's last message
+  # when it is the model's. The list starts from the refs it already has
+  # (re-validated), so a later hook run never loses them.
+  class AnswerRefs
+    KEY = :display_refs
+    MAX_REFS = 200
+    # The list's JSON; a ref that would cross it is refused.
+    MAX_BYTES = 256 * 1024
+
+    # Stored refs (+raw+, as read from session.json or a snapshot), each
+    # rebuilt and checked again, the caps applied; what isn't valid any
+    # more is dropped. Never raises: a reload must show the conversation.
+    # A relative file path is dropped (there is no folder to resolve it).
+    # @return [Array<Hash>] the refs to send ({match:, kind:, target:, …})
+    def self.for_display(raw)
+      return [] if raw.nil?
+
+      kept = new([{ role: "model", KEY => raw }], cwd: nil).to_a
+      dropped = raw.is_a?(Array) ? raw.length - kept.length : 1
+      Log.debug(:web, "display_refs_dropped", count: dropped) if dropped.positive?
+      kept
+    rescue StandardError
+      []
+    end
+
+    # @return [Hash, nil] the message event[:refs] adds to
+    attr_reader :target
+
+    # @param messages [Array<Hash>] the conversation the turn stored
+    # @param cwd [String, nil] the session's folder, for relative file paths
+    def initialize(messages, cwd:)
+      last = Array(messages).last
+      @target = last if last.is_a?(Hash) && (last[:role] || last["role"]).to_s == "model"
+      @cwd = cwd
+      @refs = []
+      @seen = {}
+      @bytes = 2 # the list's []
+      @added = false
+      @closed = false
+      @rejections = Hash.new(0)
+      seed(@target) if @target
+    end
+
+    # True when a hook added a ref the answer didn't have.
+    def added? = @added
+
+    def count = @refs.length
+
+    # @return [Array<Hash>] the refs as stored ({match:, kind:, target:, …})
+    def to_a = @refs.dup
+
+    # The list is stored (Engine#store_answer_display): a later call (a
+    # plugin that kept event[:refs]) would be lost, so it returns nil.
+    def close! = @closed = true
+
+    def closed? = @closed
+
+    # event[:refs]: call it with the ref's keywords,
+    # +call(match:, kind:, target:, label: nil, actions: [])+.
+    # @param event [Hash] the after_turn event (for its :hook label)
+    # The hook's label is read at call time: one adder serves every hook of
+    # the fire, and the registry sets event[:hook] before each.
+    # @return [Proc] true when the ref is kept (or was already there), false
+    #   when it is refused (logged, named by event[:hook]), nil when the
+    #   turn has no answer or the list was already stored (#close!)
+    def adder(event)
+      lambda do |*args, **ref|
+        next nil unless @target
+        next late(event[:hook]) if @closed
+        next reject(event[:hook], "takes keywords (match:, kind:, target:, label:, actions:)") unless args.empty?
+
+        add(ref, event[:hook])
+      end
+    end
+
+    private
+
+    KEYS = %i[match kind target label actions].freeze
+    REASON_VALUES = /\(.*?\)|\[.*?\]|".*?"|\d+/
+    private_constant :KEYS, :REASON_VALUES
+
+    def seed(target)
+      raw = target[KEY] || target[KEY.to_s]
+      raw.each { |entry| keep(entry) } if raw.is_a?(Array)
+    end
+
+    def add(value, hook)
+      unknown = value.keys - KEYS
+      return reject(hook, "has unknown keys #{unknown.map(&:to_s).inspect}") unless unknown.empty?
+
+      entry = AnswerRef.from(value, cwd: @cwd).to_h
+      return true if @seen.key?(entry)
+      return over_cap(hook, "#{MAX_REFS} refs") if @refs.length >= MAX_REFS
+
+      size = JSON.generate(entry).bytesize + (@refs.empty? ? 0 : 1)
+      return over_cap(hook, "#{MAX_BYTES / 1024} KiB") if @bytes + size > MAX_BYTES
+
+      push(entry, size)
+      @added = true
+    rescue StandardError => e
+      reject(hook, e.message)
+    end
+
+    # A stored entry back in the list, checked again (a relative path is
+    # dropped: it was stored absolute). Duplicates and what is over the
+    # caps go quietly.
+    # @return [Boolean] kept
+    def keep(raw)
+      entry = AnswerRef.from(raw, cwd: nil).to_h
+      return false if @seen.key?(entry) || @refs.length >= MAX_REFS
+
+      size = JSON.generate(entry).bytesize + (@refs.empty? ? 0 : 1)
+      return false if @bytes + size > MAX_BYTES
+
+      push(entry, size)
+      true
+    rescue StandardError
+      false
+    end
+
+    def push(entry, size)
+      @refs << entry
+      @seen[entry] = true
+      @bytes += size
+    end
+
+    def over_cap(hook, cap) = reject(hook, "over the cap (#{cap})")
+
+    def late(hook)
+      Log.debug(:hooks, "refs_late", hook: hook.to_s)
+      nil
+    end
+
+    # Each reason is said once per hook per answer (a warn and its echo);
+    # the same again goes to debug with its count, so a hook looping over
+    # bad refs can't flood the terminal. The reason's values (a kind, a
+    # key list, a cap) don't make it a new one.
+    def reject(hook, why)
+      count = @rejections[[hook.to_s, why.gsub(REASON_VALUES, "")]] += 1
+      if count == 1
+        Log.warn(:hooks, "refs_rejected", echo: "[samagotchi:hooks] #{hook}: ref #{why}; dropped",
+                                          hook: hook.to_s, reason: why)
+      else
+        Log.debug(:hooks, "refs_rejected", hook: hook.to_s, reason: why, count: count)
+      end
+      false
+    end
+  end
+end

data/lib/samagotchi/bootstrap_command.rb

@@ -41,7 +41,8 @@ module Samagotchi
         With no config.yml it writes one; an existing one gets a hosts:
         entry added (after a backup), and its other lines stay as they are.
         Then it installs the system bundle and the core bundles (loop-guard,
-        check-in, guardrails), and on a terminal offers the dev bundles.
+        check-in, guardrails, slow-commands, agents-md), and on a terminal
+        offers the dev bundles.
     TEXT
 
     FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) do |f|

data/lib/samagotchi/bridge/card_store.rb

@@ -45,7 +45,11 @@ module Samagotchi
     # its own), and a question still open when the worker went waits for no
     # one: neither is saved or seeded. Same caps as in memory. An entry from
     # an earlier worker lists with +earlier+: true (an attached TUI's resync
-    # onto a new worker doesn't print those again).
+    # onto a new worker doesn't print those again). An earlier card shown
+    # during a turn (+in_turn+) comes back without its actions: they belong
+    # to a turn no worker runs any more (check-in's Nudge would steer the
+    # new worker's turn). A card shown between turns (github-pr's offer,
+    # btw, coordinator) keeps its buttons.
     class CardStore
       CAPACITY = 20
       NOTICE_TYPES = %i[hook_notice guardrail_warning empty_answer_retry steer_cut].freeze
@@ -137,6 +141,7 @@ module Samagotchi
           next unless entry.is_a?(Hash) && entry[:type].is_a?(String) && entry[:turns].is_a?(Integer)
 
           entry = entry.merge(type: entry[:type].to_sym, earlier: true)
+          entry = entry.merge(actions: []) if entry[:type] == :card && entry[:in_turn] && entry.key?(:actions)
           entry unless entry[:type] == :guardrail_warning || open_question?(entry)
         end
         settle_during(after_turn: false)

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -118,6 +118,7 @@ module Samagotchi
         return [] unless turn
 
         started = { type: :turn_started, prompt: turn[:prompt], origin: turn[:origin], continue: !!turn[:continue] }
+        started[:resumed] = true if turn[:resumed]
         started[:started_at] = started_at if started_at
         events = [with_images(started, turn[:images])]
         text_iteration = nil # a text part is open for this iteration
@@ -238,6 +239,7 @@ module Samagotchi
           dequeue([event[:origin]])
           @turn = { prompt: event[:prompt], origin: event[:origin], continue: !!event[:continue],
                     parts: [], pending_question: nil }
+          @turn[:resumed] = true if event[:resumed]
           @tool_started_at = {}
           @turn[:images] = event[:images] if event[:images]
           @turn[:cut_after] = event[:cut_after] if event[:cut_after]

data/lib/samagotchi/bundles/agents-md/manifest.yml

@@ -0,0 +1,11 @@
+---
+name: agents-md
+version: 0.1.0
+scope: system
+description: "Steers a nested AGENTS.md into the conversation the first time a tool touches a file under its directory"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:fba1b4b48fa99299aa4c5b56999f5083513f7eb22d85f3fd2a5c2dbd0d97c707
+# ctx.prompt_files, read when the plugin loads (0.60.0)
+requires_chi: ">= 0.60.0"

data/lib/samagotchi/bundles/agents-md/plugin.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+# The agents-md bundle (docs/plugins.md, The agents-md bundle): a nested
+# AGENTS.md of the session's checkout is steered into the conversation the
+# first time a tool touches a file under its directory.
+#
+# chi's system prompt holds only the AGENTS.md chain from the checkout top
+# down to the session's cwd (SystemPrompt#prompt_files), so an AGENTS.md in
+# a directory the session doesn't run in (pkg/inner/AGENTS.md while the
+# session runs in pkg/) is never seen. Working on a nested file usually
+# means its directory's rules apply, so the first ok `read`, `write` or
+# `edit` (settings tools) of such a file steers the nearest AGENTS.md into
+# the running turn, at the loop's next boundary, as its own user message:
+#
+#   AGENTS.md for pkg/inner/ (applies to work under pkg/inner/):
+#   <content>
+#
+# It is history, not system prompt: the prompt cache is untouched, and a
+# resume, a woken worker or a fork (which copies the messages) never
+# re-injects — a before_turn pass over event[:messages] replaces the loaded
+# set with the dirs whose steer is already in the conversation. A steer
+# that was queued but dropped (the model answered first) is not in the
+# messages, so it fires again on the next touch. It never stops generation
+# or thinking; a plugin steer can't cut (SteerCut#cut_for_steer).
+#
+# Paths are compared by File.realpath, falling back to File.expand_path for
+# a path that doesn't exist: the session's cwd can be /tmp/x on macOS while
+# git and the prompt's files give /private/tmp/x. The touched file's own git
+# root must equal the session's checkout (ctx.repo_root): a file in another
+# repository, a nested repository or a submodule is ignored, and the walk up
+# stops at that root. Directories whose AGENTS.md is already in the system
+# prompt (ctx.prompt_files: the chain and appended files) or already steered
+# are skipped.
+#
+# Settings (config.yml, bundles: agents-md:):
+#   tools: [read, write, edit]   the calls that count as a touch
+#   max_chars: 16000            the content is cut at this many chars, the
+#                               last line "[cut at N of M chars: read <path>
+#                               for the rest]" naming the file by its absolute path
+#
+# skip_agents_md: true (top-level) disables the plugin, as it does the
+# chain's loading.
+
+require "samagotchi/config"
+require "samagotchi/guardrails/context"
+
+class Plugin
+  FILE_NAME = "AGENTS.md"
+  DEFAULT_TOOLS = %w[read write edit].freeze
+  DEFAULT_MAX_CHARS = 16_000
+  # The marker on the steer's first line (and what #rebuild matches):
+  # <rel dir>/ is relative to the checkout top, so a dir is unique.
+  MARKER = %r{\AAGENTS\.md for (.+)/ \(applies to work under \1/\):\n}
+
+  def initialize(settings = {})
+    tools = settings["tools"]
+    @tools = if tools.nil?
+               DEFAULT_TOOLS
+             elsif tools.is_a?(Array)
+               tools.map(&:to_s)
+             else
+               tools.to_s.split(/\s+/).reject(&:empty?)
+             end
+    chars = settings["max_chars"]
+    chars = chars.to_i if chars
+    @max_chars = chars.is_a?(Integer) && chars.positive? ? chars : DEFAULT_MAX_CHARS
+    @git = Samagotchi::Guardrails::GitInfo.new
+    # session_id => {rel dir => true}: the dirs steered this session.
+    @loaded = Hash.new { |hash, id| hash[id] = {} }
+    @lock = Mutex.new
+  end
+
+  def register(chi)
+    # Replaces the loaded set from the conversation: a dropped steer fires
+    # again on the next touch, a resume or a fork rebuilds from its messages.
+    chi.on(:before_turn) { |event, ctx| rebuild(event, ctx) }
+    chi.on(:after_tool_call) { |event, ctx| on_tool(event, ctx) }
+  end
+
+  # An ok touch of a file under a directory with a nested AGENTS.md steers
+  # each candidate (the file's directory up to, not including, the checkout
+  # top; outermost first) once per session.
+  def on_tool(event, ctx)
+    return if Samagotchi::Config.get("skip_agents_md") == true
+    return unless @tools.include?(event[:tool].to_s)
+    return unless event[:status].to_s == "ok"
+
+    call = event[:call] || {}
+    # The path a hook sees (docs/hooks.md): read on content:, write/edit on
+    # path:, expanded against the session's cwd.
+    raw = (event[:tool].to_s == "read" ? call[:content] : call[:path]).to_s.strip
+    return if raw.empty?
+
+    path = resolve(raw, base: ctx.cwd)
+    top = resolve(ctx.repo_root)
+    return if top.nil?
+
+    # Scope: the file's own git root must be the session's checkout (a
+    # nested repository, a submodule or another repository is ignored).
+    file_root = resolve(@git.root(File.dirname(path)))
+    return unless file_root && file_root == top
+
+    prompt_files = Set.new(ctx.prompt_files.map { |file| resolve(file) })
+    count = 0
+    candidate_dirs(path, top).reverse_each do |dir|
+      agents = File.join(dir, FILE_NAME)
+      next unless File.file?(agents)
+      next if prompt_files.include?(resolve(agents)) # in the system prompt already
+      next if loaded(ctx).key?(relative_dir(dir, top))
+
+      text = steer_text(dir, top, agents)
+      next unless text
+
+      # Queued: the dir is loaded; a steer dropped before it was injected
+      # (the model answered first) is not queued, so it fires again later.
+      count += 1 if ctx.steer(text) && (loaded(ctx)[relative_dir(dir, top)] = true)
+    end
+    ctx.log.info(:agents_md_steered, file: File.basename(path), n: count) if count.positive?
+  end
+
+  private
+
+  # The dirs between +path+'s directory and +top+, file's directory first
+  # (the caller reverses for outermost-first).
+  def candidate_dirs(path, top)
+    dirs = []
+    dir = File.dirname(path)
+    prefix = top.end_with?("/") ? top : "#{top}/"
+    while dir != top && dir.start_with?(prefix)
+      dirs << dir
+      parent = File.dirname(dir)
+      break if parent == dir
+
+      dir = parent
+    end
+    dirs
+  end
+
+  # +dir+ relative to +top+ ("." for +top+ itself), or nil when it isn't under it.
+  def relative_dir(dir, top)
+    prefix = top.end_with?("/") ? top : "#{top}/"
+    return "." if dir == top
+    return nil unless dir.start_with?(prefix)
+
+    dir.delete_prefix(prefix)
+  end
+
+  # The steer: the marker first line (what #rebuild matches), the content,
+  # cut at max_chars with a pointer at the end. Nil when there is nothing to say.
+  def steer_text(dir, top, agents)
+    content = File.read(agents, encoding: "UTF-8")
+    return nil if content.strip.empty?
+
+    rel_dir = relative_dir(dir, top)
+    header = "AGENTS.md for #{rel_dir}/ (applies to work under #{rel_dir}/):"
+    return "#{header}\n#{content}" if content.length <= @max_chars
+
+    body = content[0...@max_chars]
+    "#{header}\n#{body}\n[cut at #{@max_chars} of #{content.length} chars: read #{agents} for the rest]"
+  rescue SystemCallError, EncodingError
+    nil
+  end
+
+  # Replaces the loaded set with the dirs whose steer the conversation
+  # already carries (a user message, kind steer, source agents-md, the
+  # marker on its first line).
+  def rebuild(event, ctx)
+    id = event[:session_id] || ctx.session_id
+    found = {}
+    Array(event[:messages]).each do |message|
+      next unless message.is_a?(Hash)
+      next unless (message[:role] || message["role"]).to_s == "user"
+      next unless (message[:kind] || message["kind"]).to_s == "steer"
+      next unless (message[:source] || message["source"]).to_s == "agents-md"
+
+      if (match = MARKER.match((message[:content] || message["content"]).to_s))
+        found[match[1]] = true
+      end
+    end
+    @lock.synchronize { @loaded[id] = found }
+  end
+
+  # +path+ (relative ones against +base+) by File.realpath, falling back to
+  # File.expand_path when it doesn't exist; nil for an empty one.
+  def resolve(path, base: nil)
+    path = path.to_s
+    return nil if path.empty?
+
+    path = File.expand_path(path, base) if base && !File.absolute_path?(path)
+    File.realpath(path)
+  rescue SystemCallError
+    File.expand_path(path, base || Dir.pwd)
+  end
+
+  def loaded(ctx)
+    @lock.synchronize { @loaded[ctx.session_id] }
+  end
+end

data/lib/samagotchi/bundles/check-in/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: check-in
-version: 0.2.3
+version: 0.2.4
 scope: system
 description: "Checks on a long turn: after N tool calls with no answer, a card asks the user (Nudge / Keep going / Stop), or the model is nudged to say what it has found"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:821aea2821df12f278db9a94f8150244e67bf9453735d19a5abe9d94253eefa6
+  sha256: sha256:42fe075c664d256ecb8623b76a25d5c389e42c0534a41c56fe17b073d521e095
 requires_chi: ">= 0.3.0"

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

@@ -11,6 +11,10 @@
 # final answer is dropped: the card's Nudge then says so at the turn's end
 # (after_turn's messages have no steer with its text).
 #
+# One nudge per check-in: a second Nudge (a repeat click, a stale card's
+# button, a typed /checkin nudge) for the same check-in only says it was
+# already nudged; before the turn's first check-in, one nudge in all.
+#
 # The count is per turn: before_turn resets it (and closes a card left open
 # by a turn that failed or was interrupted, where after_turn doesn't fire);
 # steering merged mid-turn does not. The /checkin commands are anytime ones
@@ -76,6 +80,8 @@ class Plugin
     @card_id = nil  # this turn's card, once shown
     @card_open = false
     @nudge = nil    # the card's Nudge this turn: { text:, count: }
+    @checked_in = nil # the count at this turn's latest check-in
+    @nudged_for = nil # the check-in (its count, :none before one) nudged
   end
 
   def before_turn(ctx)
@@ -97,6 +103,7 @@ class Plugin
       next nil unless @enabled && @count >= @next_at
 
       @next_at = @count + @every
+      @checked_in = @count
       [@count, @mode]
     end
     check_in(ctx, *due) if due
@@ -107,7 +114,10 @@ class Plugin
     when "nudge"
       text = message(count)
       if ctx.steer(text)
-        @mutex.synchronize { @nudge = { text: text, count: count } }
+        @mutex.synchronize do
+          @nudge = { text: text, count: count }
+          @nudged_for = count
+        end
         ctx.notify("nudged the model after #{count} tool calls")
       end
     when "notify"
@@ -232,10 +242,24 @@ class Plugin
     "check-in after #{n} tool calls, then every #{n}, for this session"
   end
 
+  # At most one nudge per check-in; the slot is taken before the steer (two
+  # clicks race on the anytime command's threads) and given back when no
+  # turn took it.
   def nudge(ctx)
-    count = calls
+    count, key, earlier = @mutex.synchronize do
+      key = @checked_in || :none
+      next [nil, nil, @nudge&.dig(:count) || @count] if @nudged_for == key
+
+      @nudged_for = key
+      [@count, key, nil]
+    end
+    return "check-in: already nudged at #{earlier} tool calls" if earlier
+
     text = message(count)
-    return "check-in: no turn running" unless ctx.steer(text)
+    unless ctx.steer(text)
+      @mutex.synchronize { @nudged_for = nil if @nudged_for == key }
+      return "check-in: no turn running"
+    end
 
     @mutex.synchronize { @nudge = { text: text, count: count } }
     close_card(ctx, "Nudged the model at #{count} tool calls.")

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

@@ -1,6 +1,6 @@
 ---
 name: core
-version: 0.2.0
+version: 0.3.0
 scope: system
 description: "Recommended safety set"
 trust_level: reviewed
@@ -10,3 +10,4 @@ includes:
 - check-in
 - guardrails
 - slow-commands
+- agents-md

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

@@ -121,7 +121,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 1. **Read** the current file via `read` tool (or `ConfigFile.global_path`). If `File.file?` false, start from `{}`.
 2. `YAML.safe_load` (permitted_classes: [], aliases: false). If data nil or not Hash, treat as `{}` or raise with path.
 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_agents_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.
+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_agents_md`; names under `hosts:`/`models:`/`model_aliases:`/`hooks:`/`bundles:`/`memories:`/`append_system_prompt:` 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:`, 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`).
 

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.59.0
+version: 0.61.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:dfc19266259a9af1e0d769b7e0f67996b740b0c9921fdf3dadad973f6e5c144a
-  config_modification_protocol.md: sha256:44a35f59baf44202972c9250989daa50eb978ab2a1967159e622c74ddd9c736c
+  config_modification_protocol.md: sha256:16403da5dd97a335e19d9d15bb1ba4390237bf9f4869e35d63c172a8828b5ae0
   memory_guide.md: sha256:d16919387c42d229498f470fc4078245a15faee872480ffbeffe2e27897624e4
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/config.rb

@@ -223,7 +223,7 @@ module Samagotchi
       Entry.new(key: "steer.cut_after",          yaml_path: %w[steer cut_after],          type: :integer, default: 20,              expose: %i[env config]),
       # A turn's step limit: model ↔ tool rounds before it stops and offers to continue (IterationLimit); integer ≥ 1.
       # --no-interrupt turns get max(1000, this). No CLI flag: --no-interrupt is the flag.
-      Entry.new(key: "turn.max_iterations",      yaml_path: %w[turn max_iterations],      type: :integer, default: 100,             expose: %i[env config]),
+      Entry.new(key: "turn.max_iterations",      yaml_path: %w[turn max_iterations],      type: :integer, default: 300,             expose: %i[env config]),
       # Whether a parent agent (chi answer) may answer Continue to a session's step-limit question; false: Stop only.
       # config.yml only, like guardrails.parent_approvals: a parent must not decide it from its own environment.
       Entry.new(key: "turn.parent_continue",     yaml_path: %w[turn parent_continue],     type: :bool,    default: true,            expose: %i[config]),
@@ -272,10 +272,10 @@ module Samagotchi
       Entry.new(key: "skip_agents_md",           yaml_path: %w[skip_agents_md],           type: :bool,   default: false,            expose: %i[env config])
     ].freeze
 
-    # Top-level maps read by their own code, whose entry names and contents
-    # are the user's: ConfigFile.model_aliases / preloaded_memories,
-    # Hooks::Loader, Engine#read_bundle_settings.
-    FREE_FORM_MAPS = %w[model_aliases hooks bundles memories].freeze
+    # Top-level maps and lists read by their own code, whose entry names and
+    # contents are the user's: ConfigFile.model_aliases / preloaded_memories /
+    # appended_prompt_files, Hooks::Loader, Engine#read_bundle_settings.
+    FREE_FORM_MAPS = %w[model_aliases hooks bundles memories append_system_prompt].freeze
     # Maps of named entries and the keys an entry may hold
     # (ConfigFile.hosts_config, ConfigFile.model_settings).
     MAP_ENTRY_KEYS = {
@@ -987,6 +987,34 @@ module Samagotchi
       []
     end
 
+    # Resolve the `append_system_prompt:` list: files whose text goes into
+    # the system prompt after AGENTS.md (SystemPrompt). A YAML list of
+    # strings or a single string; ~ is expanded, a relative entry is kept as
+    # written (resolved against the cwd the prompt is built in). [] when
+    # the key is absent or malformed.
+    # @return [Array<String>]
+    def appended_prompt_files(env: ENV, path: global_path(env: env))
+      data = read_yaml(env: env, path: path)
+      raw = data["append_system_prompt"] if data.is_a?(Hash)
+      items = case raw
+              when Array then raw
+              when String then [raw]
+              else []
+              end
+      items.select { |v| v.is_a?(String) }.map(&:strip).reject(&:empty?).filter_map { |v| expand_appended_entry(v) }
+    rescue StandardError
+      []
+    end
+
+    # An append_system_prompt: entry with ~ expanded; nil (skipped, logged)
+    # for a ~user that doesn't exist, so the other entries still load.
+    def expand_appended_entry(entry)
+      entry.start_with?("~") ? File.expand_path(entry) : entry
+    rescue ArgumentError => e
+      Samagotchi::Log.warn(:config, "appended_prompt_file_skipped", entry: entry, error: e.message) if defined?(Samagotchi::Log)
+      nil
+    end
+
     # Parse a model string that may be qualified as "host_alias:model"
     # Returns [host_alias_or_nil, bare_model] (ModelRef.split)
     def parse_host_qualified_model(raw, hosts: nil)