samagotchi 0.12.0 → 0.13.0

data/lib/samagotchi/question_desk.rb

@@ -7,6 +7,7 @@ require "time"
 
 require_relative "log"
 require_relative "tools/ask_user_question"
+require_relative "guardrails/parent_approvals"
 
 module Samagotchi
   # An Engine's question flow: the one open question (ask_user_question, a
@@ -21,6 +22,20 @@ module Samagotchi
     # of ArgumentError for existing callers; transports map it to 409 Conflict.
     class NotPending < ArgumentError; end
 
+    # Raised by #answer when a parent agent's answer (chi answer's client
+    # id) allows an approval further than this worker's
+    # guardrails.parent_approvals lets it (Guardrails::ParentApprovals).
+    # The question stays open; transports map it to 403.
+    class Refused < StandardError
+      # @return [Symbol] :off or :once_only
+      attr_reader :reason
+
+      def initialize(reason)
+        @reason = reason
+        super("a parent may not allow this approval (#{reason})")
+      end
+    end
+
     DISMISSED_NOTE = "The user dismissed the question without answering. Don't do what you asked about, " \
                      "or anything else that changes files or state. Finish your reply with what you found " \
                      "and what you would do, and wait."
@@ -170,11 +185,16 @@ module Samagotchi
     # @param id [String] pending id
     # @param selected [Array<String>] values/labels
     # @param freeform [String, nil]
+    # @param client_id [String, nil] who answers; chi answer's (a parent
+    #   agent) is held to guardrails.parent_approvals on an approval
     # @return [Hash] normalized answer
-    def answer(id:, selected:, freeform: nil)
+    # @raise [NotPending, ArgumentError, Refused]
+    def answer(id:, selected:, freeform: nil, client_id: nil)
       sel = Array(selected).map { |v| v.to_s.strip }.reject(&:empty?)
       fm = freeform.to_s.strip
       fm = nil if fm.empty?
+      # Read before the lock (config may touch the disk); this worker's own.
+      parent_setting = Guardrails::ParentApprovals.setting if client_id.to_s == Guardrails::ParentApprovals::CLIENT_ID
       @lock.synchronize do
         pending = @pending
         raise NotPending, "no pending question" unless pending
@@ -197,10 +217,17 @@ module Samagotchi
         if pending[:multi_select] == false && sel.empty? && fm.nil?
           raise ArgumentError, "selection required"
         end
+        indices = sel.map { |v| opts.index(v) }
+        # Checked against the question pending now, under the lock: the one
+        # whose answer settles the approval (Approval.settle, by index).
+        if parent_setting
+          reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: parent_setting)
+          raise Refused, reason if reason
+        end
         # Persist pending cleared elsewhere; just set answer
         answer = { id: id.to_s, selected: sel, freeform: fm }
         # Derive indices for convenience
-        answer[:selected_indices] = sel.map { |v| opts.index(v) }.compact
+        answer[:selected_indices] = indices.compact
         @answer = answer
         @cv.broadcast
         answer

data/lib/samagotchi/recap_setup.rb

@@ -13,7 +13,8 @@ module Samagotchi
     # host or model configured it asks the session's current model on its
     # host, resolved at each attempt the way a turn does (a /model switch
     # counts). An explicit `recap: {host_ref:, model:}` or `{base_url:,
-    # model:}` pins it; an incomplete one warns and leaves recap off.
+    # model:}` pins it; a model alone goes to its host, or where a bare
+    # --model goes; an incomplete one warns and leaves recap off.
     #
     # Single precedence path: explicit `recap:` kwarg > Config registry
     # (CLI > ENV > file > default). An explicit disable (`recap: false` as
@@ -42,14 +43,23 @@ module Samagotchi
       model = string_config(kwarg_config, :model) || registry_string("recap.model")
       label = model
 
+      # The model as any model ref (ModelRef): its alias applied once, and
+      # its host (own or the alias's) picks the recap host when host_ref
+      # doesn't.
+      parsed = model && host_registry.model_ref(model)
       target = nil
       if base_url.nil? && host_ref.nil? && model.nil?
         target = -> { session_target.call }
+      elsif base_url.nil? && host_ref.nil? && !parsed.host_name
+        # A model naming no host goes where a bare --model goes
+        # (HostRegistry#host_for_model: the default host unless another's
+        # list has it), resolved at each attempt.
+        target = lambda do
+          resolved = host_registry.resolve(model)
+          { base_url: resolved.openai_base_url, api_key_env: resolved.entry.api_key_env,
+            model: resolved.bare_model, label: label.to_s.strip }
+        end
       else
-        # The model as any model ref (ModelRef): its alias applied once, and
-        # its host (own or the alias's) picks the recap host when host_ref
-        # doesn't.
-        parsed = model && host_registry.model_ref(model)
         host_ref ||= parsed.host_name if parsed && base_url.nil?
         # If host_ref given, derive base_url (the host's OpenAI base) and its
         # API key variable from the host_registry entry

data/lib/samagotchi/reply_wait.rb

@@ -72,8 +72,12 @@ module Samagotchi
           return Result.new(status: :stopped)
         end
 
+        # Only a question a live worker holds waits for an answer (the
+        # lists' rule): one a dead worker left waits for no one, and a chi
+        # REPL's is answered there.
         pending = session.pending_question
-        if pending && !(baseline && pending[:id] == baseline[:question_id])
+        if pending && !(baseline && pending[:id] == baseline[:question_id]) &&
+           session.waiting_question(live: SessionManager.worker_live?(id, state_dir: state_dir))
           return Result.new(status: :waiting_for_answer, question: pending)
         end
 

data/lib/samagotchi/send_command.rb

@@ -5,12 +5,14 @@ require_relative "session_inbox"
 require_relative "session_manager"
 require_relative "context_quote"
 require_relative "reply_wait"
+require_relative "parent_report"
 require_relative "image_store"
 require_relative "host_registry"
 require_relative "model_profile"
 require_relative "vision_support"
 require_relative "cli/command"
 require_relative "cli/flags"
+require_relative "cli/parent_wait"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -22,20 +24,17 @@ module Samagotchi
   # prints it: an agent's one-shot the user can watch in the web.
   class SendCommand
     include CLI::Command
+    include CLI::ParentWait
 
     CLIENT_ID = "cli:send"
-    POLL_INTERVAL = ReplyWait::POLL_INTERVAL
-    # No live worker this long while waiting: it died before it could mark
-    # the session (a worker takes well under a second to start).
-    WORKER_GONE_AFTER = 5
     # The cap on one turn's images the Bridge checks.
     MAX_IMAGES = ImageStore::MAX_TURN_REFS
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
              chi send --new [--dir DIR] [--model M] [-m TEXT] [--image PATH]...
-             chi send --wait [--timeout S] [-m TEXT] [--image PATH]... (--new | ID)
-             chi send --wait [--timeout S] ID
+             chi send --wait [--timeout S] [--format json] [-m TEXT] [--image PATH]... (--new | ID)
+             chi send --wait [--timeout S] [--format json] ID
         Sends a message to each session, as if typed in it: a turn starts,
         or a running one picks it up. A stopped session's worker starts.
         -m TEXT     the message; stdin, when piped too, goes above it as a
@@ -53,11 +52,21 @@ module Samagotchi
         --model M   (--new) its model; default the configured one
         --wait      wait for the answer and print it (one session); the
                     other lines go to stderr. Exit 3: it waits for an
-                    answer from you (chi --attach ID or the web). With
-                    no message (no -m, nothing piped) nothing is sent: it
-                    waits for the session's next reply, a running turn's
-                    too (after exit 3 or 130, wait again this way)
-        --timeout S (--wait) give up after S seconds; default no limit
+                    answer from you: the question, its options and the
+                    chi answer command go to stderr (or chi --attach ID,
+                    the web). With no message (no -m, nothing piped)
+                    nothing is sent: it waits for the session's next
+                    reply, a running turn's too (after exit 3, 4 or 130,
+                    wait again this way)
+        --timeout S (--wait) give up after S seconds, exit 4 (the turn
+                    goes on); default no limit
+        --format json
+                    (--wait) one JSON object on stdout, whatever the end:
+                    status answered (text), question (question,
+                    answer_with), running, or failed, canceled,
+                    no_answer, error, worker_gone, stopped (detail)
+        Exit with --wait: 0 answered, 1 failed or gone, 2 usage, 3 a
+        question waits, 4 still running (--timeout), 130 Ctrl-C.
         Only sessions on this machine. Answers show in the attached TUI
         or web page, not here.
         Find ids with: chi sessions list --live [--scope=all] [--format tsv]
@@ -71,6 +80,7 @@ module Samagotchi
       f.value "--image", key: :images, repeat: true
       f.switch "--wait"
       f.value "--timeout"
+      f.value "--format"
       # Starting a turn in every live session at once is too easy to do
       # by accident.
       f.refuse "--all", "there is no --all: name the sessions"
@@ -119,13 +129,13 @@ module Samagotchi
       @state_dir = state_dir || Session.default_state_dir
     end
 
-    # @return [Integer] exit status: 0 all sent, 1 any refused or failed,
-    #   2 usage; with --wait 0 answered, 3 waiting for an answer, 130
-    #   Ctrl-C (the turn goes on)
-    def run
-      options = parse
-      return options if options.is_a?(Integer)
+    private
 
+    # Under #run (CLI::ParentWait).
+    # @return [Integer] exit status: 0 all sent, 1 any refused or failed,
+    #   2 usage; with --wait 0 answered, 3 waiting for an answer, 4 still
+    #   running after --timeout, 130 Ctrl-C (the turn goes on)
+    def run_parsed(options)
       # With --wait stdout is the answer alone.
       @info = options[:wait] ? @stderr : @stdout
       prompt = compose(utf8(read_stdin), utf8(options[:message]))
@@ -140,7 +150,9 @@ module Samagotchi
         @stderr.puts("chi send: #{e.message}")
         return 1
       end
-      return 2 unless ingest_images(options[:images])
+      # A file that is not there or not an image: a run-time failure (1),
+      # reported in the --format json line too; --image itself was fine.
+      return CLI::Exit::FAILED unless ingest_images(options[:images])
 
       return run_new(prompt, options) if options[:new]
       return run_wait(prompt, options) if options[:wait]
@@ -160,8 +172,6 @@ module Samagotchi
       FileUtils.rm_rf(@image_dir) if @image_dir
     end
 
-    private
-
     def command_name = "chi send"
 
     # @return [Hash, Integer] the options, or the exit status after the
@@ -171,6 +181,10 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       options = parsed.options.merge(ids: parsed.args)
+      if options[:format]
+        return usage_error("--format needs --wait") unless options[:wait]
+        return usage_error("--format takes text or json") unless FORMATS.include?(options[:format])
+      end
       if options[:timeout]
         return usage_error("--timeout needs --wait") unless options[:wait]
 
@@ -220,16 +234,6 @@ module Samagotchi
       @stdin.read
     end
 
-    def resolve(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
-      Session.load(id, state_dir: @state_dir)
-      id
-    rescue ArgumentError => e
-      message = e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"
-      error_line("chi send: #{message}")
-      nil
-    end
-
     # A worker session like the web start page's: saved as running with the
     # message before its worker spawns, so lists and the web show it at
     # once. The full id, so a script can pass it on. Only the model's host
@@ -257,6 +261,7 @@ module Samagotchi
       else
         @info.puts("#{session.id}  started")
       end
+      @session_id = session.id
       return 0 unless options[:wait]
 
       wait_for_reply(session.id, cursor: nil, baseline: baseline_of(session, question_id: nil),
@@ -272,8 +277,20 @@ module Samagotchi
     def run_wait(prompt, options)
       id = resolve(options[:ids].first) or return 1
       session = Session.load(id, state_dir: @state_dir)
-      if session.status == Session::STATUS_RUNNING && SessionManager.session_owner(id, state_dir: @state_dir)
-        error_line("#{id[0, 8]}  busy: a turn is running; wait or attach")
+      if session.status == Session::STATUS_RUNNING && (owner = SessionManager.session_owner(id, state_dir: @state_dir))
+        # The turn waits on a question: the message would only queue
+        # behind it, and the answer goes in with chi answer.
+        if (waiting = session.waiting_question(live: owner.worker?))
+          if ParentReport.approval?(waiting)
+            error_line("#{id[0, 8]}  waiting for an approval: #{ParentReport::DENY_AND_TELL} " \
+                       "(#{ParentReport.answer_with(id, waiting)})")
+          else
+            error_line("#{id[0, 8]}  waiting for an answer: #{ParentReport.answer_with(id, waiting)} (or --text); " \
+                       "chi --attach #{id} shows it")
+          end
+        else
+          error_line("#{id[0, 8]}  busy: a turn is running; wait or attach")
+        end
         return 1
       end
 
@@ -298,7 +315,7 @@ module Samagotchi
       live = session.status == Session::STATUS_RUNNING || SessionManager.session_owner(id, state_dir: @state_dir)
       wait_for_reply(id, cursor: ReplyWait.newest_reply(id, state_dir: @state_dir),
                          baseline: baseline_of(session).merge(messages: nil),
-                         timeout: options[:timeout], owner_grace: live ? WORKER_GONE_AFTER : nil)
+                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil)
     end
 
     # The session as it was before the message went in (ReplyWait's
@@ -307,48 +324,6 @@ module Samagotchi
       ReplyWait.baseline_of(session, **options)
     end
 
-    # @return [Integer] the exit status
-    def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: WORKER_GONE_AFTER)
-      result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
-                                  owner_grace: owner_grace, poll_interval: POLL_INTERVAL)
-      return reply(result.text) if result.status == :done
-
-      attach = "chi --attach #{id}"
-      line, status = case result.status
-                     when :waiting_for_answer
-                       question = result.question[:question].to_s.strip.lines.first.to_s.strip
-                       ["waiting for an answer: #{question}; open it: #{attach} or the web", 3]
-                     when :no_reply then ["#{no_reply_line(result)}; #{attach} shows it", 1]
-                     when :error then ["the worker failed: #{result.text}; #{attach} shows what happened", 1]
-                     when :worker_gone then ["the worker is gone; #{attach} shows what happened", 1]
-                     when :stopped then ["the session was stopped (chi sessions stop)", 1]
-                     else ["still running after #{format("%g", timeout)} s: #{attach}", 1]
-                     end
-      error_line("chi send: #{line}")
-      status
-    rescue Interrupt
-      error_line("chi send: still running: chi --attach #{id}")
-      130
-    rescue ArgumentError
-      error_line("chi send: the session is gone (deleted while waiting)")
-      1
-    end
-
-    def no_reply_line(result)
-      case result.outcome
-      when "failed" then result.text.to_s.strip.empty? ? "the turn failed" : "the turn failed: #{result.text.strip}"
-      when "canceled" then "the turn was canceled"
-      when "completed" then "the turn ended with no visible answer"
-      else "the turn ended without a reply (canceled, failed or empty)"
-      end
-    end
-
-    def reply(text)
-      @stdout.puts(utf8(text))
-      @stdout.flush
-      0
-    end
-
     # A new idle session's first turn, with the images. Its worker's Bridge
     # first: deliver_turn wakes a worker when none owns the session yet,
     # and the spawned one takes its lock only once it runs.

data/lib/samagotchi/session.rb

@@ -99,6 +99,21 @@ module Samagotchi
       @archived = false
     end
 
+    # The question this session waits on, as the lists show it: {id:, kind:}
+    # with kind "question" (the model's), "approval" or "hook"; nil with
+    # none. Only while a worker runs it (+live+): a question saved by a
+    # worker that died waits for no one (the next worker drops it). The
+    # web's summaries and `chi sessions list` both ask this.
+    # @param live [Boolean] a worker owns the session now
+    # @return [Hash, nil]
+    def waiting_question(live:)
+      pending = pending_question
+      return nil unless live && pending.is_a?(Hash) && pending[:id]
+
+      kind = pending[:kind].to_s
+      { id: pending[:id], kind: %w[approval hook].include?(kind) ? kind : "question" }
+    end
+
     # The stored project root, else (a file from before the field) the
     # project of the working directory now: nil when that is in no repo or
     # gone. +cache+ is ProjectScope.root_for's, shared across one listing.

data/lib/samagotchi/session_manager.rb

@@ -162,7 +162,9 @@ module Samagotchi
     # child inherits this process's ENV and reads config.yml itself (as it
     # is when the worker starts); opts[:env] adds to it (merged, not
     # replaced) what it can't read there: this `chi`'s CLI settings
-    # (Config.cli_env), the hosts and the absolute log file.
+    # (Config.cli_env), the hosts and the absolute log file. It unsets
+    # SAMAGOTCHI_GUARDRAILS_*. XDG_CONFIG_HOME passes: whoever starts or
+    # wakes the worker picks which config.yml it reads (docs/guardrails.md).
     private_class_method def self.spawn_options(session)
       # Own process group: workers outlive `chi web`, and a Ctrl-C in its
       # terminal must not reach them.
@@ -195,10 +197,17 @@ module Samagotchi
       else
         child_env["SAMAGOTCHI_LOG_DISABLE"] = "true"
       end
+      # The spawner's environment must not reach the worker's guardrails (a
+      # parent agent starting or waking a session): Process.spawn unsets a
+      # key mapped to nil. config.yml no longer reads them; this keeps an
+      # older or future env-exposed one out as well.
+      ENV.each_key { |key| child_env[key] = nil if key.start_with?(GUARDRAILS_ENV_PREFIX) }
       opts[:env] = child_env unless child_env.empty?
       opts
     end
 
+    GUARDRAILS_ENV_PREFIX = "SAMAGOTCHI_GUARDRAILS_"
+
     # List all sessions, reading status from persisted session.json files.
     # +project_root+: only that project's sessions (nil: every session).
     # +include_archived+: archived sessions too (Session#archived says which).
@@ -226,9 +235,11 @@ module Samagotchi
     # @param include_archived [Boolean] archived sessions too
     # @return [Array<Hash>] {id:, short_id:, desc:, preview:, cwd:, project:,
     #   updated_at:, status:, live:, busy:, owner:, recap:, parent_id:,
-    #   parent_short_id:, archived:, scratch:, test_run:}; busy = live with
+    #   parent_short_id:, archived:, scratch:, test_run:, waiting:, waiting_id:}; busy = live with
     #   a turn running, recap = the saved recap's first sentence, project =
-    #   Session#project_root
+    #   Session#project_root, waiting = the kind of question it waits on
+    #   ("question", "approval", "hook"; Session#waiting_question) or nil,
+    #   waiting_id = that question's id or nil
     def self.session_summaries(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
                                project_root: nil, include_archived: false, sort: nil, order: nil)
       sd = state_dir || Session.default_state_dir
@@ -239,20 +250,27 @@ module Samagotchi
                          .reject { |s| (!include_tests && s.test_run) || s.id == exclude }
                          .select { |s| root.nil? || in_folder?(s.working_directory, root) }
                          .filter_map do |s|
-        owner = session_owner(s.id, state_dir: sd)&.kind
-        owned = owner == "worker"
+        owner = session_owner(s.id, state_dir: sd)
+        owned = !!owner&.worker?
         next if live && !owned
 
         { id: s.id, short_id: s.id[0, 8], desc: summary_desc(s), preview: summary_preview(s), cwd: s.working_directory,
           project: s.project_root(cache: roots), updated_at: s.updated_at, status: s.status, live: owned, busy: owned && s.status == Session::STATUS_RUNNING,
-          owner: owner, recap: RecapStore.preview(Session.session_dir(s.id, state_dir: sd)),
+          owner: owner&.kind, recap: RecapStore.preview(Session.session_dir(s.id, state_dir: sd)),
           ctx_pct: SessionMetrics.saved_context_pct(Session.session_dir(s.id, state_dir: sd))&.round(1),
           parent_id: s.parent_id, parent_short_id: s.parent_id&.[](0, 8), archived: s.archived,
-          scratch: s.scratch, test_run: s.test_run }
+          scratch: s.scratch, test_run: s.test_run }.merge(waiting_fields(s.waiting_question(live: owned)))
       end
       (limit ? summaries.first(limit) : summaries.to_a)
     end
 
+    # waiting: the question's kind, waiting_id: its id (what chi answer
+    # --question takes); both nil with none.
+    def self.waiting_fields(waiting)
+      { waiting: waiting&.dig(:kind), waiting_id: waiting&.dig(:id) }
+    end
+    private_class_method :waiting_fields
+
     # The sessions delegated by +parent_id+ (the `delegate` tool), newest
     # first, as .session_summaries rows. A running one (busy) counts against
     # session.max_children. Archived ones too.
@@ -831,6 +849,15 @@ module Samagotchi
       OwnerLock.owner(Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir))
     end
 
+    # A worker owns the session now: the one rule for whether a saved
+    # pending question waits for anyone (Session#waiting_question's live:).
+    # A chi REPL's question is its own (nothing else can answer it), and one
+    # a dead worker saved waits for no one.
+    # @return [Boolean]
+    def self.worker_live?(session_id, state_dir: nil)
+      !!session_owner(session_id, state_dir: state_dir)&.worker?
+    end
+
     # The session's owner (#session_owner), unless it is the interactive
     # TUI, which nothing else may resume, stop or delete.
     # @return [OwnerLock::Owner, nil]

data/lib/samagotchi/sessions_command.rb

@@ -146,13 +146,20 @@ module Samagotchi
         # scratch: a `chi scratch` session (deleted when its REPL ends, a
         # leftover one at the next sweep)
         # ctx_pct: how full the context was after the last turn, or nil
-        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id archived scratch ctx_pct]
+        # waiting: the kind of question it waits on (question, approval,
+        # hook: chi answer or the web answers it), or nil; waiting_id: its
+        # id, for chi answer --question
+        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id archived scratch ctx_pct waiting
+                  waiting_id]
         @stdout.puts JSON.generate(summaries.map { |summary| summary.slice(*keys) })
       when "tsv"
         summaries.each { |summary| @stdout.puts "#{summary[:id]}\t#{summary[:desc]}" }
       else
         summaries.each do |summary|
-          state = summary[:busy] ? "running" : (summary[:live] ? "live" : summary[:status].to_s)
+          state = if summary[:waiting] then "waiting"
+                  elsif summary[:busy] then "running"
+                  else summary[:live] ? "live" : summary[:status].to_s
+                  end
           # The saved recap's first sentence says more than the last prompt
           # (text only: tsv and json keep desc for pickers).
           desc = summary[:desc]
@@ -197,7 +204,10 @@ module Samagotchi
         ctx = Samagotchi::SessionMetrics.context_label(
           Samagotchi::SessionMetrics.saved_context_pct(Samagotchi::Session.session_dir(s.id, state_dir: state_dir))
         )
-        "#{s.id}  #{s.status.ljust(8)}  #{ctx.ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
+        # A question waits for an answer (chi answer, the web, chi --attach).
+        live = s.pending_question && Samagotchi::SessionManager.worker_live?(s.id, state_dir: state_dir)
+        status = s.waiting_question(live: !!live) ? "waiting" : s.status
+        "#{s.id}  #{status.ljust(8)}  #{ctx.ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
       end
       if project
         sessions.each { |s| @stdout.puts row.call(s) }

data/lib/samagotchi/system_prompt.rb

@@ -328,11 +328,12 @@ module Samagotchi
 
     # ── Project / rg helpers ───────────────────────────────────────────────────
 
+    # AGENT.md in the cwd, else at the top of its git work tree.
     def project_specific_description
       return nil if skip_agent_description?
 
-      path = File.join(Dir.pwd, AGENT_DESCRIPTION_FILE)
-      return nil unless File.file?(path)
+      path = agent_description_path
+      return nil unless path
 
       content = File.read(path).strip
       return nil if content.empty?
@@ -342,6 +343,13 @@ module Samagotchi
       nil
     end
 
+    def agent_description_path
+      cwd = Dir.pwd
+      [cwd, MemoryPaths.work_tree_root(cwd)].compact.uniq
+        .map { |dir| File.join(dir, AGENT_DESCRIPTION_FILE) }
+        .find { |path| File.file?(path) }
+    end
+
     # Where the session runs and which project memory folder it uses. The root
     # line appears only when it differs from the cwd (a worktree or subdir).
     # The home directory is spelled out once so the model copies the right

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -5,6 +5,8 @@ require_relative "../config"
 require_relative "../model_profile"
 require_relative "../session_manager"
 require_relative "../bridge_client"
+require_relative "../parent_report"
+require_relative "../cli/exit"
 require_relative "live_region"
 require_relative "plain_surface"
 require_relative "attached_loop"
@@ -43,14 +45,40 @@ module Samagotchi
                          memories: memories, muted_memories: muted_memories)
         first_command = model && (attach || resume) ? "/model #{model}" : nil
         surface = open_surface
-        begin
-          AttachedLoop.new(client: client, screen: surface, client_id: "tui:#{Process.pid}", first_prompt: prompt,
-                           first_command: first_command, no_interrupt: no_interrupt,
-                           default_input: default_input && !prompt && !attach && !resume,
-                           wait_at_eof: !$stdin.tty?).run
+        attached = AttachedLoop.new(client: client, screen: surface, client_id: "tui:#{Process.pid}", first_prompt: prompt,
+                                first_command: first_command, no_interrupt: no_interrupt,
+                                default_input: default_input && !prompt && !attach && !resume,
+                                wait_at_eof: !$stdin.tty?,
+                                parent_answers: Guardrails::ParentApprovals.parent_process?)
+        ended = begin
+          attached.run
         ensure
           close_surface(surface)
         end
+        report_unanswered(attached.unanswered, session_id: client.session_id) if ended == :unanswered && attached.unanswered
+        ended
+      end
+
+      # A question left waiting (exit 3), in full on stderr as `chi send
+      # --wait` prints it (ParentReport), so a script or a parent agent
+      # can answer it with chi answer.
+      # @param pending [Hash] the pending question (symbol keys)
+      def report_unanswered(pending, session_id:, err: $stderr)
+        err.print("chi: #{ParentReport.question_text(pending, session_id: session_id)}")
+        err.flush
+      end
+
+      # chi's exit status after #run: 0 detached, 3 a question left waiting
+      # for an answer (input from a pipe ran out; chi --attach or chi answer
+      # answers it), 1 anything else (a failed turn, the worker gone).
+      # @param ended [Symbol] what #run returned
+      # @return [Integer]
+      def exit_status(ended)
+        case ended
+        when :detached then CLI::Exit::OK
+        when :unanswered then CLI::Exit::QUESTION
+        else CLI::Exit::FAILED
+        end
       end
 
       # A live region (Screen, with Reline drawing into it) on a terminal

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -20,6 +20,7 @@ require_relative "../model_profile"
 require_relative "../output_formatter"
 require_relative "../session_commands"
 require_relative "../session_manager"
+require_relative "../guardrails/parent_approvals"
 
 module Samagotchi
   class TerminalUI
@@ -62,6 +63,10 @@ module Samagotchi
       # @return [QuestionPrompt, nil] the question waiting for an answer
       attr_reader :question
 
+      # @return [Hash, nil] the pending question (symbol keys) #run left
+      #   waiting when it ended :unanswered
+      attr_reader :unanswered
+
       # @param client [BridgeClient]
       # @param screen [Surface] with #synchronize and #columns (a Screen, or a
       #   PlainSurface when the terminal can't show a live region)
@@ -81,7 +86,7 @@ module Samagotchi
       #   X </dev/null`): at their end, detach only once this run's prompts
       #   (the -p one too) have had their turns; if one failed, #run says so
       def initialize(client:, screen:, client_id:, first_prompt: nil, first_command: nil, no_interrupt: false,
-                     default_input: false, wait_at_eof: false,
+                     default_input: false, wait_at_eof: false, parent_answers: false,
                      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
                      delete_session: ->(id) { SessionManager.delete_session(id, stop: true, wait: DELETE_WAIT) },
                      archive_session: ->(id) { SessionManager.archive_session(id, wait: DELETE_WAIT) })
@@ -90,6 +95,10 @@ module Samagotchi
         @archive_session = archive_session
         @screen = screen
         @client_id = client_id
+        # A parent agent drives this attach (AttachLauncher:
+        # ParentApprovals.parent_process?): its answers go as chi answer's,
+        # so the worker holds them to guardrails.parent_approvals.
+        @parent_answers = parent_answers
         @view = AttachedView.new(screen)
         @renderer = EventRenderer.new(@view)
         @shown_enqueued = Set.new
@@ -158,7 +167,7 @@ module Samagotchi
             if payload.nil? && @wait_at_eof && own_turns_pending?
               # The pipe's end: this run's turns first. An open question
               # has nothing left to answer it.
-              return unanswered_question if @question
+              return unanswered_question(@question_pending) if @question
 
               next @input_ended = true
             end
@@ -217,7 +226,7 @@ module Samagotchi
         when :input_merged then merged_own_prompts(event)
         when :question_requested
           # Nothing is left to answer it with.
-          return unanswered_question if @input_ended
+          return unanswered_question(event[:pending_question]) if @input_ended
 
           ask(event[:pending_question])
         when :question_answered then question_answered(event)
@@ -557,7 +566,8 @@ module Samagotchi
         @own_failed ? :turn_failed : :detached
       end
 
-      def unanswered_question
+      def unanswered_question(pending)
+        @unanswered = pending
         detach("A question waits for an answer: chi --attach #{@client.session_id}")
         :unanswered
       end
@@ -634,6 +644,7 @@ module Samagotchi
         # What was typed at the prompt waits for the question to close.
         @set_aside = @reader&.typed_text unless @question
         @question = QuestionPrompt.new(pending)
+        @question_pending = pending
         # An edit's diff goes above, into the scrollback, once per question
         # (a join gets it from the snapshot and may get the event too).
         unless @previewed_id == @question.id
@@ -656,7 +667,8 @@ module Samagotchi
           return @screen.commit(answer.error)
         end
 
-        reply = @client.answer(id: @question.id, selected: answer.selected, freeform: answer.freeform)
+        parent = @parent_answers ? { client_id: Guardrails::ParentApprovals::CLIENT_ID } : {}
+        reply = @client.answer(id: @question.id, selected: answer.selected, freeform: answer.freeform, **parent)
         case reply.status
         when 200
           @answered_ids << @question.id