samagotchi 0.2.0

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

@@ -0,0 +1,100 @@
+# The btw bundle (docs/plugins.md, The btw bundle): /btw <question> asks the
+# session's model a side question about the conversation. The answer shows
+# as a card in every UI and goes nowhere else: the conversation, the saved
+# session and the model's next turn never see it. The card's "Keep as
+# session" (/btw keep <id>) turns it into a child session that starts from
+# the conversation, the question and the answer.
+#
+# Settings (config.yml, bundles: btw:): max_tokens (the answer's limit,
+# default 1024) and timeout (seconds, default 120).
+require "securerandom"
+
+class Plugin
+  SYSTEM = "Answer the user's question about the conversation below, briefly. The user asks it on the side: " \
+           "don't continue the conversation's task, and don't say what you would do next."
+  # How many answers /btw keep can still fork: the last ones, for the
+  # worker's (or the REPL's) life.
+  KEPT = 10
+  TITLE_CHARS = 72
+  EARLIER = "(About the conversation before the running turn.)"
+
+  def initialize(settings = {})
+    @max_tokens = positive(settings["max_tokens"])
+    @timeout = positive(settings["timeout"]) || 120
+    @answers = {}
+    @mutex = Mutex.new
+  end
+
+  def register(chi)
+    chi.command "/btw", "ask a side question about this conversation; /btw keep <id> makes an answer a session",
+                anytime: true do |args, ctx|
+      if (keep = args[/\Akeep\s+(\S+)\z/, 1])
+        keep(keep, ctx)
+      elsif args.empty?
+        "usage: /btw <question> — a side answer about this conversation, as a card; nothing is saved"
+      else
+        ask(args, ctx)
+      end
+    end
+  end
+
+  private
+
+  # A card at once, then the same card with the answer.
+  def ask(question, ctx)
+    id = SecureRandom.hex(4)
+    card_id = "btw-#{id}"
+    title = "btw: #{cut(question)}"
+    messages = ctx.messages
+    about = ctx.messages_partial? ? "\n\n#{EARLIER}" : ""
+    ctx.card(id: card_id, title: title, body: "thinking…#{about}")
+    answer = begin
+      ctx.ask_model(messages: messages, prompt: question, system: SYSTEM, timeout: @timeout, max_tokens: @max_tokens)
+    rescue Samagotchi::Plugin::ModelError => e
+      ctx.card(id: card_id, title: title, body: "No answer: #{e.message}", level: :warn)
+      return nil
+    end
+    answer = "(the model gave no answer)" if answer.strip.empty?
+    remember(id, messages: messages, question: question, answer: answer, card_id: card_id, title: title, about: about)
+    ctx.card(id: card_id, title: title, body: "#{answer}#{about}",
+             actions: [{ label: "Keep as session", command: "/btw keep #{id}" }])
+    nil
+  end
+
+  # A child session from the conversation the answer was about, plus the
+  # question and the answer.
+  def keep(id, ctx)
+    entry = @mutex.synchronize { @answers[id] }
+    return "btw keep #{id}: expired (answers are kept for the last #{KEPT} questions, while this session's worker runs)" unless entry
+    return "btw keep #{id}: already kept as session #{entry[:child]}" if entry[:child]
+
+    seed = entry[:messages] + [{ role: "user", content: entry[:question] }, { role: "model", content: entry[:answer] }]
+    child = ctx.sessions.fork(messages: seed, title: "btw: #{entry[:question]}")
+    @mutex.synchronize { entry[:child] = child }
+    # The answer's card loses its action: it is kept.
+    ctx.card(id: entry[:card_id], title: entry[:title], body: "#{entry[:answer]}#{entry[:about]}")
+    ctx.card(title: "kept as #{child[0, 8]}",
+             body: "A session with this conversation, the question and the answer: `chi --attach #{child}`, " \
+                   "or pick it in the web (↳ under this session).")
+    nil
+  rescue Samagotchi::Plugin::Sessions::Error => e
+    "btw keep #{id}: #{e.message}"
+  end
+
+  def remember(id, **entry)
+    @mutex.synchronize do
+      @answers[id] = entry
+      @answers.delete(@answers.keys.first) while @answers.size > KEPT
+    end
+  end
+
+  def cut(text)
+    line = text.gsub(/\s+/, " ").strip
+    line.length > TITLE_CHARS ? "#{line[0, TITLE_CHARS - 1]}…" : line
+  end
+
+  def positive(value)
+    number = Integer(value.to_s, exception: false)
+    number&.positive? ? number : nil
+  end
+end

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

@@ -0,0 +1,82 @@
+# Default guardrail rules (the optional guardrails bundle:
+# `chi bundle install guardrails`). Text matches on shell commands catch
+# accidents, not a determined model: `sh -c`, base64, a script written
+# 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),
+# 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).
+rules:
+  # ── git: publishing and rewriting history ──────────────────────────────
+  - id: git-push
+    tool: shell
+    command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+push\b'
+    verdict: ask
+    reason: git push publishes commits
+  - id: git-reset-hard
+    tool: shell
+    command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+reset\b[^;&|\n]*\s--hard\b'
+    verdict: ask
+    reason: git reset --hard discards uncommitted work
+  - id: git-clean-force
+    tool: shell
+    command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+clean\b[^;&|\n]*\s(-[a-zA-Z]*f|--force)'
+    verdict: ask
+    reason: git clean -f deletes untracked files
+  - id: git-branch-force-delete
+    tool: shell
+    command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+branch\b[^;&|\n]*\s(-[a-zA-Z]*D|--delete\s+--force|--force\s+--delete)\b'
+    verdict: ask
+    reason: git branch -D deletes a branch even if it is not merged
+  - id: git-rebase
+    tool: shell
+    command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+rebase\b'
+    verdict: ask
+    reason: git rebase rewrites history
+  - id: git-history-rewrite
+    tool: shell
+    command: '\bgit(?:\s+(?:-C\s+\S+|-c\s+\S+|--?[A-Za-z][\w-]*(?:=\S+)?))*\s+(filter-branch|filter-repo)\b'
+    verdict: ask
+    reason: filter-branch / filter-repo rewrite the whole history
+
+  # ── deleting ───────────────────────────────────────────────────────────
+  # rm with both -r and -f on an absolute path, ~, $HOME or a path with ..
+  # (a text heuristic; rm -rf build/ in the repo is not asked).
+  - id: rm-rf-wide
+    tool: shell
+    command: '\brm\b(?=[^;&|\n]*\s(-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)(\s|$))(?=[^;&|\n]*\s(-[a-zA-Z]*f[a-zA-Z]*|--force)(\s|$))[^;&|\n]*\s(/|~|\$HOME|\S*\.\.)'
+    verdict: ask
+    reason: rm -rf on a path outside the working tree
+
+  # ── running code from the network ──────────────────────────────────────
+  - id: pipe-to-shell
+    tool: shell
+    command: '\b(curl|wget)\b[^;&\n]*\|\s*(sudo\s+)?(ba|z|da)?sh\b'
+    verdict: ask
+    reason: runs a script downloaded from the network
+  - id: base64-to-shell
+    tool: shell
+    command: '\bbase64\s+(-d|-D|--decode)\b[^;&\n]*\|\s*(sudo\s+)?(ba|z|da)?sh\b'
+    verdict: ask
+    reason: runs decoded text as a script
+
+  # ── files outside the repo, and git hooks ──────────────────────────────
+  - id: write-outside-repo
+    tool: [write, edit]
+    path: outside_repo
+    verdict: ask
+    reason: writes outside the repository
+  - id: git-hooks-write
+    tool: [write, edit]
+    path: '**/.git/hooks/**'
+    verdict: deny
+    reason: git hooks run code on every git command
+
+  # ── chi's own config, hooks, rules and approvals, from the shell ───────
+  - id: shell-touches-chi
+    tool: shell
+    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

data/lib/samagotchi/bundles/guardrails/guardrails.md

@@ -0,0 +1,14 @@
+# Guardrails
+
+Some tool calls pass a guardrail check before they run. The user sets the rules (config.yml `guardrails:`, installed bundles such as this one, and hooks). Chi itself also protects its approval store, installed bundles, config.yml and the hooks dir.
+
+- **ask**: the user sees the call (tool, command or paths, where, why) and allows it once, for the session, for this repo, or for the whole rule in this repo, or denies it.
+- **deny**: the call does not run.
+
+A call a rule or hook denies comes back as `[tool] Error: denied by guardrail (rule <id>, <source>): <reason>. …`. A call the user declined when asked comes back as `[tool] Error: The user declined this call… It needed approval (rule <id>, <source>): <reason>. …`, sometimes with the user's reason: that is the user's answer, not the rule's.
+
+When a call is denied:
+- Do not retry it, and do not reach the same result another way: a different command, `sh -c`, a script, another tool, or editing the rules, hooks or config.
+- Say what you wanted to do and why, and ask the user how to proceed.
+
+`/guardrails` lists the rules and the user's stored approvals (the user can revoke them there). The approvals and installed bundles cannot be written with the file tools.

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

@@ -0,0 +1,8 @@
+---
+name: guardrails
+version: 0.1.1
+scope: system
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, writes outside the repo, git hooks) and a note for the model
+trust_level: reviewed
+files:
+  guardrails.md: sha256:04207fd1738aeeeef3b7a8053fc57597565bddd7862f01acaba784419cbd909b

data/lib/samagotchi/bundles/known-names/hooks/known_names.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+# A before_tool_call guard against near-misses of protected identifiers in
+# a tool call's command or paths: the user's home folder name, login, git
+# name and email, the repo name, and any names from config. A local model
+# that once misspelled a name in a path keeps copying the wrong spelling;
+# a rejection that names the right one breaks the loop.
+#
+# Settings (config.yml, `bundles: known-names:`), all optional:
+#   names: [jonathandoe]         names to protect besides the derived ones
+#   mode: reject                 reject (default) | correct | ask
+#   derive: [home, user, git, repo]   which names to derive (default all)
+#   ignore: [jondoe]             names never to protect (a real near name)
+#   min_length: 6                shorter names and tokens are skipped
+#   max_distance: 2              edits allowed; default 1 for a name under
+#                                10 characters, 2 otherwise
+class KnownNames
+  MODES = %w[reject ask correct].freeze
+  DERIVATIONS = %w[home user git repo].freeze
+  DEFAULT_MIN_LENGTH = 6
+  # Splits a command or path into tokens; each token's [-_.] parts are
+  # candidates too.
+  TOKEN_SPLIT = %r{[/\s"'=:,;|&()<>@]+}.freeze
+  PART_SPLIT = /[-_.]+/.freeze
+  ASK_OPTIONS = ["Correct it and run", "Run as is", "Deny"].freeze
+
+  def initialize(settings = {})
+    settings = {} unless settings.is_a?(Hash)
+    @names = list(settings["names"])
+    @ignore = list(settings["ignore"]).map(&:downcase)
+    @mode = MODES.include?(settings["mode"].to_s) ? settings["mode"].to_s : "reject"
+    derive = settings.key?("derive") ? list(settings["derive"]) & DERIVATIONS : DERIVATIONS
+    @derive = derive
+    @min_length = [settings["min_length"].to_i, 1].max
+    @min_length = DEFAULT_MIN_LENGTH if settings["min_length"].nil?
+    max = settings["max_distance"].to_i
+    @max_distance = max.positive? ? max : nil
+    @git_cache = {}
+  end
+
+  def call(event)
+    return unless event.is_a?(Hash) && event[:type] == :before_tool_call
+
+    hit = find_near_miss(event)
+    return unless hit
+
+    case @mode
+    when "correct" then correct(event, hit)
+    when "ask" then ask(event, hit)
+    else reject(event, hit)
+    end
+  rescue StandardError => e
+    event[:notify]&.call("known-names failed: #{e.class}: #{e.message}", level: :warn)
+  end
+
+  # Damerau-Levenshtein distance (optimal string alignment: an adjacent
+  # transposition counts as one edit).
+  def self.distance(a, b)
+    a = a.to_s
+    b = b.to_s
+    return b.length if a.empty?
+    return a.length if b.empty?
+
+    prev2 = nil
+    prev = (0..b.length).to_a
+    a.each_char.with_index(1) do |ca, i|
+      row = [i]
+      b.each_char.with_index(1) do |cb, j|
+        cost = ca == cb ? 0 : 1
+        best = [prev[j] + 1, row[j - 1] + 1, prev[j - 1] + cost].min
+        if i > 1 && j > 1 && ca == b[j - 2] && a[i - 2] == cb
+          best = [best, prev2[j - 2] + 1].min
+        end
+        row << best
+      end
+      prev2 = prev
+      prev = row
+    end
+    prev.last
+  end
+
+  private
+
+  # The first candidate that is a near miss of a known name.
+  # @return [Hash, nil] {miss:, name:, distance:, where:}
+  def find_near_miss(event)
+    names = known_names(event)
+    return nil if names.empty?
+
+    scan_targets(event).each do |where, text|
+      candidates(text).each do |candidate|
+        down = candidate.downcase
+        next if names.key?(down)
+
+        names.each do |name_down, name|
+          max = @max_distance || (name.length < 10 ? 1 : 2)
+          next if (candidate.length - name.length).abs > max
+
+          d = self.class.distance(down, name_down)
+          return { miss: candidate, name: name, distance: d, where: where } if d.between?(1, max)
+        end
+      end
+    end
+    nil
+  end
+
+  # [where, text] pairs to scan: the command, the cwd a command names,
+  # each path, and a write/edit call's own path (in case normalisation
+  # dropped it). Not file contents.
+  def scan_targets(event)
+    targets = event[:targets].is_a?(Hash) ? event[:targets] : {}
+    call = event[:call].is_a?(Hash) ? event[:call] : {}
+    pairs = []
+    pairs << ["command", targets[:command].to_s] unless targets[:command].to_s.empty?
+    pairs << ["cwd", call[:cwd].to_s] unless call[:cwd].to_s.strip.empty?
+    Array(targets[:paths]).each { |path| pairs << ["path", path.to_s] }
+    pairs << ["path", call[:path].to_s] if %w[write edit].include?(call[:name].to_s) && !call[:path].to_s.empty?
+    pairs
+  end
+
+  def candidates(text)
+    text.split(TOKEN_SPLIT).flat_map { |token| [token] + token.split(PART_SPLIT) }
+        .uniq.select { |c| c.length >= @min_length }
+  end
+
+  # downcased name => name as given, minus ignored and short ones
+  def known_names(event)
+    names = @names + derived_names(event)
+    names.each_with_object({}) do |name, acc|
+      next if name.length < @min_length
+      down = name.downcase
+      next if @ignore.include?(down) || acc.key?(down)
+
+      acc[down] = name
+    end
+  end
+
+  def derived_names(event)
+    names = []
+    names << File.basename(Dir.home) if @derive.include?("home")
+    names << ENV["USER"].to_s if @derive.include?("user")
+    context = event[:context].is_a?(Hash) ? event[:context] : {}
+    root = context[:repo_root].to_s
+    names << File.basename(root) if @derive.include?("repo") && !root.empty?
+    names.concat(git_names(root)) if @derive.include?("git") && !root.empty?
+    names.map(&:to_s).map(&:strip).reject(&:empty?)
+  rescue StandardError
+    names
+  end
+
+  # The words of git's user.name and the local part of user.email, one
+  # git call per repo root.
+  def git_names(root)
+    @git_cache[root] ||= begin
+      name = git_config(root, "user.name")
+      email = git_config(root, "user.email")
+      name.split(/\s+/) + [email.split("@").first.to_s]
+    end
+  end
+
+  def git_config(root, key)
+    IO.popen(["git", "-C", root, "config", "--get", key], err: File::NULL, &:read).to_s.strip
+  rescue StandardError
+    ""
+  end
+
+  def reject(event, hit)
+    tool = event[:call].is_a?(Hash) ? event[:call][:name] : nil
+    edits = hit[:distance] == 1 ? "1 edit" : "#{hit[:distance]} edits"
+    event[:guardrail]&.deny!(
+      "\"#{hit[:miss]}\" in the #{hit[:where]} is #{edits} away from the known name \"#{hit[:name]}\"",
+      source: "hook known_names, bundle known-names",
+      advice: "Retry with \"#{hit[:name]}\". If \"#{hit[:miss]}\" is really what you meant, say so to the user instead of retrying."
+    )
+    event[:notify]&.call("rejected #{tool}: \"#{hit[:miss]}\" looks like \"#{hit[:name]}\"")
+  end
+
+  # The same call with the near miss replaced (whole tokens, everywhere it
+  # appears in the content, path and cwd).
+  def correct(event, hit)
+    call = event[:call]
+    pattern = /(?<![A-Za-z0-9])#{Regexp.escape(hit[:miss])}(?![A-Za-z0-9])/
+    fixed = call.dup
+    %i[content path cwd].each do |key|
+      next unless fixed[key].is_a?(String)
+
+      fixed[key] = fixed[key].gsub(pattern, hit[:name])
+    end
+    event[:call] = fixed
+    event[:notify]&.call("corrected \"#{hit[:miss]}\" → \"#{hit[:name]}\" in #{call[:name]}")
+  end
+
+  def ask(event, hit)
+    tool = event[:call].is_a?(Hash) ? event[:call][:name] : nil
+    answer = event[:ask_user]&.call(
+      question: "#{tool}: #{event[:params]}\n\"#{hit[:miss]}\" looks like a misspelling of \"#{hit[:name]}\".",
+      options: ASK_OPTIONS, header: "known-names"
+    )
+    choice = answer.is_a?(Hash) ? Array(answer[:selected]).first.to_s : ""
+    case choice
+    when ASK_OPTIONS[0] then correct(event, hit)
+    when ASK_OPTIONS[1] then nil
+    else reject(event, hit)
+    end
+  end
+
+  def list(value)
+    Array(value).map(&:to_s).map(&:strip).reject(&:empty?)
+  end
+end

data/lib/samagotchi/bundles/known-names/known_names.md

@@ -0,0 +1,3 @@
+# Known names
+
+A tool call that comes back as `[tool] Error: denied by guardrail (hook known_names, bundle known-names): "…" in the command is N edit(s) away from the known name "…"` was caught misspelling a protected name (the user's home folder, login, git name, the repo name). Retry the same call with the name the error gives, spelled exactly like that. If the other spelling really is what you meant, say so to the user instead of retrying.

data/lib/samagotchi/bundles/known-names/manifest.yml

@@ -0,0 +1,14 @@
+---
+name: known-names
+version: 0.1.1
+scope: system
+description: Catches a near-miss of a protected name (home folder, login, git name, repo name, names from config) in a tool call and rejects it with the right spelling; mode ask / correct optional
+trust_level: reviewed
+files:
+  known_names.md: sha256:d5348b95b6c655017b541910b36e384220da280818160201f6ec9a50e1e4287c
+hooks:
+  known_names.rb:
+    sha256: sha256:2ccfe9124133d6d12499cb41ad7bdfd4ba59492c067efbf60eaa1400a7cc2504
+    event: before_tool_call
+    on_error: log
+    priority: 50

data/lib/samagotchi/bundles/loop-guard/manifest.yml

@@ -0,0 +1,10 @@
+---
+name: loop-guard
+version: 0.1.0
+scope: system
+description: "Breaks tool-call loops: the same call with the same result again and again in one turn is denied with advice, and after a few denies the turn stops with a card"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:f9e66f289f3bb92ba53e6a16ea563c16e7b814accb607a34f20585cf563b7ef5
+requires_chi: ">= 0.1.30"

data/lib/samagotchi/bundles/loop-guard/plugin.rb

@@ -0,0 +1,158 @@
+# The loop-guard bundle (docs/plugins.md, The loop-guard bundle): a model
+# that runs the same tool call again and again in one turn, getting the
+# same result each time, is told to stop (a guardrail deny with advice),
+# and after a few such denies the turn is stopped with a card that lists
+# the repeated calls.
+#
+# A call is keyed by its tool and its arguments (whitespace collapsed), its
+# result by a SHA1 of the output. Once a key has returned the same result
+# deny_after times this turn, the next identical call is denied. A denied
+# call records no result, so the deny sticks. The counts are per turn:
+# before_turn resets them (a new user message can make an old call right
+# again); steering merged mid-turn does not.
+#
+# Settings (config.yml, bundles: loop-guard:):
+#   deny_after: 2      same call + same result this many times -> deny the next
+#   stop_after: 4      stop the turn at this many loop-guard denies
+#   ignore_tools: [task_wait, task_get, delegate_result, list_sessions, list_reminders]
+#   mode: deny         deny | notify (warn once per call, never deny or stop)
+require "digest"
+
+class Plugin
+  DEFAULT_IGNORE = %w[task_wait task_get delegate_result list_sessions list_reminders].freeze
+  # Built-in tools carry flat fields; plugin and unknown tools carry args:.
+  KEY_FIELDS = %i[content path start_line end_line cwd env scope].freeze
+  SHORT_CHARS = 60
+  SOURCE = "bundle loop-guard"
+
+  def initialize(settings = {})
+    settings = {} unless settings.is_a?(Hash)
+    @deny_after = positive(settings["deny_after"]) || 2
+    @stop_after = positive(settings["stop_after"]) || 4
+    @ignore = settings.key?("ignore_tools") ? Array(settings["ignore_tools"]).map(&:to_s) : DEFAULT_IGNORE
+    @mode = settings["mode"].to_s == "notify" ? :notify : :deny
+    reset
+  end
+
+  def register(chi)
+    chi.on(:before_turn) { |_event| reset }
+    chi.on(:before_tool_call) { |event, ctx| before(event, ctx) }
+    chi.on(:after_tool_call) { |event| after(event) }
+  end
+
+  private
+
+  def reset
+    @last_result = {}  # key => result hash
+    @results = Hash.new(0) # [key, result hash] => times it ran with that result
+    @previews = {}     # key => a short form of its last result
+    @attempts = Hash.new(0) # key => calls this turn, denied ones too
+    @warned = {}       # key => true once notified this turn
+    @denials = 0
+    @pending = nil
+  end
+
+  def before(event, ctx)
+    call = event[:call]
+    verdict = event[:guardrail]
+    return unless call.is_a?(Hash) && verdict
+    return if @ignore.include?(call[:name].to_s)
+
+    key = key_for(call)
+    @pending = { key: key, verdict: verdict }
+    @attempts[key] += 1
+    # Another voter denied it already: it won't run, and isn't ours to count.
+    return if verdict.deny?
+
+    last = @last_result[key]
+    times = last ? @results[[key, last]] : 0
+    return if times < @deny_after
+
+    if @mode == :notify
+      warn(ctx, key, "repeated #{times} times with the same result")
+      return
+    end
+
+    verdict.deny!("repeated call", source: SOURCE, advice: advice(key, times))
+    warn(ctx, key, "repeated, denied")
+    @denials += 1
+    stop(event, ctx) if @denials == @stop_after
+  end
+
+  # A call's result, paired with the before_tool_call that keyed it. A call
+  # that was denied (by us or another voter) ran nothing: no result, or the
+  # deny text would become the key's result and the next call would pass.
+  def after(event)
+    pending = @pending
+    @pending = nil
+    return unless pending && event[:tool].to_s == pending[:key].first
+    return if pending[:verdict].deny?
+
+    key = pending[:key]
+    output = event[:output].to_s
+    hash = Digest::SHA1.hexdigest(output)
+    @last_result[key] = hash
+    @results[[key, hash]] += 1
+    @previews[key] = preview(output)
+  end
+
+  def stop(event, ctx)
+    event[:stop_turn]&.call("the model kept repeating the same calls")
+    repeated = @attempts.select { |key, n| n > 1 && @last_result[key] && @results[[key, @last_result[key]]] >= @deny_after }
+    lines = repeated.map do |key, n|
+      "- `#{short_key(key)}`: #{n} times, the same result each time (#{@previews[key]})"
+    end
+    ctx.card(title: "loop-guard stopped the turn",
+             body: "The model kept repeating these calls:\n\n#{lines.join("\n")}\n\n" \
+                   "Tell it what to try instead, or where to look.",
+             level: :warn)
+  end
+
+  def warn(ctx, key, what)
+    return if @warned[key]
+
+    @warned[key] = true
+    ctx.notify("loop: #{short_key(key)} #{what}", level: :warn)
+  end
+
+  def advice(key, times)
+    "You already ran this exact call #{times} times this turn and it returned the same result each time " \
+      "(#{@previews[key]}). Don't repeat it. Try a different approach, or tell the user what you're stuck on."
+  end
+
+  def key_for(call)
+    fields = call[:args].is_a?(Hash) ? call[:args] : call.slice(*KEY_FIELDS).compact
+    [call[:name].to_s, normalize(fields)]
+  end
+
+  # Strings stripped and their whitespace collapsed; keys as strings.
+  def normalize(value)
+    case value
+    when String then value.gsub(/\s+/, " ").strip
+    when Hash then value.to_h { |k, v| [k.to_s, normalize(v)] }.sort.to_h
+    when Array then value.map { |v| normalize(v) }
+    else value
+    end
+  end
+
+  def short_key(key)
+    name, fields = key
+    text = fields.is_a?(Hash) ? fields.values.map(&:to_s).reject(&:empty?).join(" ") : fields.to_s
+    "#{name} #{cut(text)}".strip
+  end
+
+  # The output without its "[tool]" label, on one line.
+  def preview(output)
+    text = output.sub(/\A\[[\w.-]+\]\s*/, "").gsub(/\s+/, " ").strip
+    text.empty? ? "no output" : cut(text)
+  end
+
+  def cut(text)
+    text.length > SHORT_CHARS ? "#{text[0, SHORT_CHARS - 1]}…" : text
+  end
+
+  def positive(value)
+    number = Integer(value.to_s, exception: false)
+    number&.positive? ? number : nil
+  end
+end

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

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