samagotchi 0.11.0 → 0.13.0

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.
@@ -765,7 +783,7 @@ module Samagotchi
     def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], state_dir: nil, manager: self, bridge: nil)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       bridge ||= -> { BridgeClient.wait_for(session_id, session_dir: session_dir, timeout: TURN_BRIDGE_WAIT) }
-      manager.resume_session(session_id, state_dir: state_dir) if manager.respond_to?(:resume_session)
+      manager.resume_session(session_id, state_dir: state_dir)
       if (client = bridge.call)
         begin
           options = { prompt: prompt, client_id: client_id }
@@ -802,9 +820,7 @@ module Samagotchi
       end
       # A worker that idle-exited since the resume never reads it either:
       # wake a new one. (The exiting worker also looks for input it left.)
-      if owner.nil? && manager.respond_to?(:session_owner) && manager.respond_to?(:resume_session)
-        manager.resume_session(session_id, state_dir: state_dir)
-      end
+      manager.resume_session(session_id, state_dir: state_dir) if owner.nil?
       { status: :accepted, ack: { status: "accepted", enqueued_id: enqueued_id, session_id: session_id } }
     end
 
@@ -814,8 +830,6 @@ module Samagotchi
     end
 
     private_class_method def self.delivery_owner(manager, session_id, state_dir)
-      return nil unless manager.respond_to?(:session_owner)
-
       manager.session_owner(session_id, state_dir: state_dir)
     rescue StandardError
       nil
@@ -835,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

data/lib/samagotchi/terminal_ui.rb

@@ -12,10 +12,10 @@ require_relative "context_note"
 require_relative "cancellation_controller"
 require_relative "llm/errors"
 require_relative "host_registry"
-require_relative "kernel_loop"
 require_relative "session"
 require_relative "owner_lock"
 require_relative "engine"
+require_relative "guardrails/parent_approvals"
 require_relative "tools/memory"
 require_relative "output_formatter"
 require_relative "turn_flow"
@@ -114,9 +114,6 @@ module Samagotchi
       # The model it starts on names a configured host (a bad default.model
       # doesn't matter when --model or the session picks another).
       ModelProfile.check_host!(@effective_model_name, hosts: @host_registry.entries)
-      # Only a caller's profile goes in; otherwise the Engine resolves one
-      # for the effective model and hands it to the kernel.
-      @kernel         = KernelLoop.new(client: @client, profile: profile, reminder_store: Samagotchi::ReminderStore.new)
       @no_default_input = no_default_input
       @non_interactive = non_interactive
       # --memory and --mute, with a resumed session's own lists first: a
@@ -157,7 +154,6 @@ module Samagotchi
         model_name: nil,
         memories: @requested_memories,
         muted_memories: @muted_memory_names,
-        kernel: @kernel,
         recap: scratch ? nil : recap_config,
         scratch: scratch,
         reminders: {
@@ -245,7 +241,9 @@ module Samagotchi
           cancel_controller: nil,
           images: ImageInput.extract(@prompt)
         )
-        if empty_answer?(result)
+        # No answer (the empty-answer retries used up): no text, or the chat
+        # loop's placeholder (LLM::ModelResult#empty_answer?).
+        if result.empty_answer?
           # Nothing to print: say so on stderr and fail, so a script that
           # pipes the answer doesn't take the silence for one.
           session.save
@@ -281,15 +279,6 @@ module Samagotchi
 
     EMPTY_ANSWER_ERROR = "chi: the model gave an empty answer"
 
-    # A -p --non-interactive turn that ended with no answer (the empty-answer
-    # retries used up): no text, or the chat loop's placeholder.
-    def empty_answer?(result)
-      return false if result.respond_to?(:canceled?) && result.canceled?
-      return false if result.respond_to?(:resumable?) && result.resumable?
-
-      result.output.to_s.strip.empty? || (result.respond_to?(:empty_answer?) && result.empty_answer?)
-    end
-
     # Delete the scratch session, the last thing the REPL does. Quiet after
     # a one-shot or on the way out of an error or a signal.
     def delete_scratch(session, quiet:)
@@ -669,7 +658,7 @@ module Samagotchi
     # After a prompt or continue turn: TurnFlow keeps the checkpoint and the
     # continue offer; the REPL saves and tells the user.
     def finish_turn(session, result, continue:)
-      if result.respond_to?(:canceled?) && result.canceled?
+      if result.canceled?
         outcome = @turn_flow.after_turn(result, continue: continue)
         # A cancelled continue is back where it started, the offer still open.
         return if outcome == :continue_cancelled
@@ -680,7 +669,7 @@ module Samagotchi
         # user's next message continues from it. !rollback restores the
         # pre-turn checkpoint for an explicit full discard (the renderer's
         # hint under :turn_canceled says so).
-        save_session(session) if result.respond_to?(:conversation) && result.conversation.is_a?(Array)
+        save_session(session) if result.conversation.is_a?(Array)
         return
       end
 
@@ -758,9 +747,9 @@ module Samagotchi
       ensure
         @surface.clear_slot(:hints)
       end
-      canceled = result.respond_to?(:canceled?) && result.canceled?
+      canceled = result&.canceled?
       if result && !canceled
-        session.messages = result.conversation if result.respond_to?(:conversation) && result.conversation.is_a?(Array)
+        session.messages = result.conversation if result.conversation.is_a?(Array)
         @engine.store_model!(session)
         session.save
       end
@@ -996,15 +985,7 @@ module Samagotchi
     end
 
     def cancelled_result_from(messages, reason:)
-      KernelLoop::Result.new(
-        output: "",
-        conversation: clone_messages(messages),
-        exhausted: false,
-        pending_tool_calls: false,
-        tool_activity: [],
-        canceled: true,
-        cancellation_reason: reason
-      )
+      LLM::ModelResult.new(text: "", conversation: clone_messages(messages), canceled: true, cancellation_reason: reason)
     end
 
     # The status row under the prompt, from the Engine's state (what a
@@ -1158,9 +1139,16 @@ module Samagotchi
         end
 
         begin
-          @engine.answer_question(id: prompt.id, selected: answer.selected, freeform: answer.freeform)
+          parent = parent_answers? ? { client_id: Guardrails::ParentApprovals::CLIENT_ID } : {}
+          @engine.answer_question(id: prompt.id, selected: answer.selected, freeform: answer.freeform, **parent)
           close_question_widget(prompt, prompt.answer_text(answer))
           return true
+        rescue QuestionDesk::Refused => e
+          # A parent's allow guardrails.parent_approvals doesn't let through:
+          # the question stays open for a deny (or the end of the input).
+          @surface.commit("#{paint(QUESTION_PROMPT, 33)}#{raw}")
+          @surface.commit(Guardrails::ParentApprovals.message(e.reason, typed: true))
+          next
         rescue ArgumentError => e
           @surface.commit("Invalid: #{e.message}. Try again.")
           next
@@ -1171,6 +1159,12 @@ module Samagotchi
       end
     end
 
+    # Whether the answers typed here are a parent agent's (piped stdin, an
+    # agent marker): QuestionDesk holds them to guardrails.parent_approvals.
+    def parent_answers?
+      Guardrails::ParentApprovals.parent_process?
+    end
+
     def close_question_widget(prompt, outcome)
       @surface.clear_slot(:notes)
       @surface.commit(prompt.summary(outcome, paint: method(:paint)))

data/lib/samagotchi/thinking.rb

@@ -65,7 +65,7 @@ module Samagotchi
       key, value = ConfigFile.model_setting(names, :thinking, models: models)
       return [value, "models: #{key}"] if key
 
-      host = target.entry.respond_to?(:thinking) ? target.entry.thinking : nil
+      host = target.entry.thinking
       return [host, "hosts.#{target.entry.name}"] if host
       return [global, "thinking.level"] if global
 

data/lib/samagotchi/thought_stream_splitter.rb

@@ -25,15 +25,15 @@ module Samagotchi
   # not a block and stays in `:text` (the model doesn't emit it; the system
   # prompt carries it).
   class ThoughtStreamSplitter
-    # Gemma 4's thought channel (ToolCallParser::Gemma strips the same pair).
-    GEMMA_THOUGHT_CHANNEL = { open: "<|channel>thought", close: "<channel|>" }.freeze
-
     # @return [Array<Hash>] each entry { open: String, close: String, lane: :thinking|:drop }
     def self.for_profile(profile)
       blocks = []
       # A thinking block needs a close marker to be bounded.
       blocks << { open: profile.thought_open, close: profile.thought_close, lane: :thinking } if profile.thought_close
-      blocks << GEMMA_THOUGHT_CHANNEL.merge(lane: :thinking) if profile.name == "gemma4"
+      # Gemma 4's thought channel (ToolCallParser::Gemma strips the same pair).
+      if profile.thought_channel_open
+        blocks << { open: profile.thought_channel_open, close: profile.thought_channel_close, lane: :thinking }
+      end
       blocks << { open: profile.tool_call_open, close: profile.tool_call_close, lane: :drop }
       new(blocks)
     end

data/lib/samagotchi/tool_call_parser.rb

@@ -38,8 +38,8 @@ module Samagotchi
       # Digits after the first character: plugin tools may have them
       # (Plugin::Api::TOOL_NAME).
       TOOL_CALL_BODY_RE   = /\Acall:([a-z_][a-z0-9_]{0,49})\{/
-      THOUGHT_CHANNEL_OPEN  = "<|channel>thought"
-      THOUGHT_CHANNEL_CLOSE = "<channel|>"
+      THOUGHT_CHANNEL_OPEN  = ModelProfile::GEMMA_THOUGHT_CHANNEL_OPEN
+      THOUGHT_CHANNEL_CLOSE = ModelProfile::GEMMA_THOUGHT_CHANNEL_CLOSE
       CONTROL_TOKEN_START = "<|"
 
       def initialize(profile)
@@ -305,10 +305,10 @@ module Samagotchi
       end
 
       def parse(text)
-        read(text).map { |call| Tools::BuiltinCalls.build(call[:name], call[:args], raw: call[:raw]) }
+        read(text).map { |call| Tools::BuiltinCalls.build(call[:name], call[:args]) }
       end
 
-      # Each <tool_call> block as {name:, args:, raw:}: its <parameter=…>
+      # Each <tool_call> block as {name:, args:}: its <parameter=…>
       # (or <arg_key>/<arg_value>) text by lowercased key, unbuilt.
       def read(text)
         results = []
@@ -324,8 +324,7 @@ module Samagotchi
 
           body = text[body_start...close_pos]
           if (name = qwen_function_name(body))
-            params = qwen_params(body)
-            results << { name: name, args: params, raw: params.to_s }
+            results << { name: name, args: qwen_params(body) }
           end
           pos = close_pos + tool_close.length
         end

data/lib/samagotchi/tool_runner.rb

@@ -146,7 +146,7 @@ module Samagotchi
     # says the image is attached, that line replaces the text.
     # @return [Array(Hash, Array<Hash>)] the result and its refs
     def attach_images(call, result)
-      vision = @kernel.vision if @kernel.respond_to?(:vision)
+      vision = @kernel.turn_settings.vision
       reason = if vision.nil? then "images can't be attached here"
                elsif !vision.sendable? then ImagePlan::CANT_SEE
                end
@@ -192,7 +192,7 @@ module Samagotchi
     end
 
     # The kernel's tools, for the activity line of a tool that isn't built in.
-    def tools = @kernel.respond_to?(:tools) ? @kernel.tools : nil
+    def tools = @kernel.tools
 
     # A tool the registry has from a plugin (not core, not unknown).
     def plugin_tool?(name)
@@ -206,8 +206,7 @@ module Samagotchi
     # The Engine sets the kernel's gate (its context, later the approval
     # flow); a bare kernel (specs) gets one that only runs the hooks.
     def gate
-      given = @kernel.guardrail_gate if @kernel.respond_to?(:guardrail_gate)
-      given || (@gate ||= Guardrails::Gate.new(-> { @kernel.hooks if @kernel.respond_to?(:hooks) }, tools_lookup: -> { tools }))
+      @kernel.guardrail_gate || (@gate ||= Guardrails::Gate.new(-> { @kernel.hooks }, tools_lookup: -> { tools }))
     end
 
     # A gate that fails denies the call (fail closed).
@@ -254,8 +253,7 @@ module Samagotchi
 
     # A failing hook must not break the turn.
     def fire(name, event)
-      hooks = @kernel.hooks if @kernel.respond_to?(:hooks)
-      hooks&.fire(name, event)
+      @kernel.hooks&.fire(name, event)
     rescue StandardError
       nil
     end

data/lib/samagotchi/tools/builtin_calls.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "../tool_declarations"
 require_relative "ask_user_question"
 
@@ -18,7 +19,7 @@ module Samagotchi
     # and the handler reading it.
     #
     # A tool that is not built in keeps its arguments whole on args: (typed
-    # by its schema at dispatch, Tools::Args) with +raw+ as its content.
+    # by its schema at dispatch, Tools::Args) with their JSON as its content.
     module BuiltinCalls
       # Per tool, what the schema alone doesn't say:
       #   content:  the property (or ordered list of keys to try) that fills
@@ -103,7 +104,7 @@ module Samagotchi
       # @param name [String]
       # @param args [Hash] string keys, as the model gave them
       # @param raw [String, nil] the call's text, the content of a tool
-      #   that isn't built in
+      #   that isn't built in when no argument could be read from it
       # @return [Hash]
       def build(name, args, raw: nil)
         name = name.to_s
@@ -139,7 +140,17 @@ module Samagotchi
       end
 
       def passthrough(name, args, raw)
-        { name: name, content: raw.nil? ? args.values.join(" ") : raw.to_s, path: nil, scope: nil, args: args }
+        { name: name, content: passthrough_content(args, raw), path: nil, scope: nil, args: args }
+      end
+
+      # The arguments as JSON, one form for every model format and Ruby
+      # version; the raw text when none could be read from it.
+      def passthrough_content(args, raw)
+        return raw.to_s if args.empty? && !raw.to_s.empty?
+
+        JSON.generate(args)
+      rescue JSON::GeneratorError
+        args.values.join(" ")
       end
     end
   end

data/lib/samagotchi/tools/builtins.rb

@@ -21,6 +21,7 @@ require_relative "send_note"
 require_relative "delegate"
 require_relative "delegate_result"
 require_relative "ask_user_question"
+require_relative "../guardrails/parent_approvals"
 
 module Samagotchi
   module Tools
@@ -72,13 +73,15 @@ module Samagotchi
         TaskCreate::NAME => lambda do |call, kctx|
           next Execute::NOT_RUN_ON_STOP if cancelled_proc(kctx).call
 
-          TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env])
+          TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env], marker_env: parent_env(kctx))
         end,
         TaskWait::NAME => lambda do |call, kctx|
           TaskWait.call(call[:content], timeout: call[:timeout], tail_lines: call[:tail_lines],
                                         done_pattern: call[:done_pattern], cancelled: cancelled_proc(kctx))
         end,
-        Execute::NAME => ->(call, kctx) { Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx)) },
+        Execute::NAME => lambda do |call, kctx|
+          Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx), env: parent_env(kctx))
+        end,
         RegisterReminder::NAME => lambda do |call, kctx|
           RegisterReminder.call(call[:content], reminder_store: kctx.reminder_store, description: call[:description],
                                                 interval_minutes: call[:interval_minutes])
@@ -99,11 +102,20 @@ module Samagotchi
 
       module_function
 
+      # What execute and task_create export into the commands they run: a
+      # chi started there answers as a parent agent
+      # (Guardrails::ParentApprovals.parent_process?), even under a PTY
+      # wrapper. The session's id, "chi" without one.
+      def parent_env(kctx)
+        id = kctx.peers.respond_to?(:session_id) ? kctx.peers.session_id.to_s : ""
+        { Guardrails::ParentApprovals::PARENT_SESSION_ENV => id.empty? ? "chi" : id }
+      end
+
       # Stop flips the turn's controller, seen through the Engine's PeerView
       # (as DelegateWait does); a bare kernel has no peers: never cancelled.
       def cancelled_proc(kctx)
         peers = kctx.peers
-        -> { peers.respond_to?(:cancelled?) && peers.cancelled? }
+        -> { !!peers&.cancelled? }
       end
 
       # @return [Registry] a new registry with the built-ins, in