samagotchi 0.61.0 → 0.62.0

data/lib/samagotchi/plugin/api.rb

@@ -79,9 +79,11 @@ module Samagotchi
       # @param targets [#call, nil] args → what guardrail rules match: a Hash
       #   with paths: (absolute or relative to the cwd), command: (a shell
       #   command) and cwd:, each optional
-      def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &)
-        spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
-                                                targets: targets, &)
+      # @param refs [#call, nil] args → the call's row's refs, display only:
+      #   a list of {kind:, target:, label:, actions:} (RowRefs, Ref). Run
+      #   once per call on the tool path, so it must be cheap (no I/O)
+      def tool(name, description, **, &)
+        spec = Api.tool_spec(name, description, **, &)
         if (taken = @registries.tools[spec[:name]])
           raise ArgumentError, "tool #{spec[:name]} is already registered (#{taken.source})"
         end
@@ -125,9 +127,8 @@ module Samagotchi
         end
 
         # As Api#tool.
-        def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &)
-          spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
-                                                  targets: targets, &)
+        def tool(name, description, **, &)
+          spec = Api.tool_spec(name, description, **, &)
           raise ArgumentError, "tool #{spec[:name]} is registered twice" if @specs.any? { |s| s[:name] == spec[:name] }
 
           @specs << spec
@@ -249,34 +250,44 @@ module Samagotchi
       def counts = { commands: @commands.size, tools: @tools.size, hooks: @hooks.size, services: @services.size,
                      inits: @inits.size }
 
-      # A checked tool declaration (#tool's arguments).
-      # @return [Hash] {name:, schema:, label:, preview:, targets:, block:}
-      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &block)
+      # A checked tool declaration (#tool's arguments: Api#tool and
+      # ToolSet#tool pass theirs on, so a new keyword is added here).
+      # @return [Hash] {name:, schema:, label:, preview:, targets:, refs:, block:}
+      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, refs: nil,
+                         &block)
         raise ArgumentError, "tool #{name.inspect} needs a block" unless block
 
         name = name.to_s
         raise ArgumentError, "tool name #{name.inspect} must be a-z, 0-9 and _ (at most 48)" unless name.match?(TOOL_NAME)
         raise ArgumentError, "tool #{name}: preview must respond to #call" if preview && !preview.respond_to?(:call)
         raise ArgumentError, "tool #{name}: targets must respond to #call" if targets && !targets.respond_to?(:call)
+        raise ArgumentError, "tool #{name}: refs must respond to #call" if refs && !refs.respond_to?(:call)
 
         parameters = schema ? schema_parameters(name, schema) : params_schema(name, params)
         { name: name, schema: { name: name, description: description.to_s, parameters: parameters },
-          label: label&.to_s, preview: preview, targets: targets, block: block }
+          label: label&.to_s, preview: preview, targets: targets, refs: refs, block: block }
       end
 
       # Make +bundle+'s tools in +registry+ the +specs+: its tools not in
       # them go; a new one, or one whose schema or label changed, is
       # registered (a changed one again, in its place: Tools::Registry
       # orders bundle tools by bundle and name); an unchanged one is kept
-      # as it is. A name another source has is left out. Called on
-      # the turn thread (Engine#apply_staged_tools!).
+      # as it is, but for its block, preview:, targets: and refs:, swapped
+      # in place: none of them reaches the prompt, so not a change (that
+      # would build the prompts again). A name
+      # another source has is left out. Called on the turn thread
+      # (Engine#apply_staged_tools!).
       # @return [Hash] {changed: Boolean, skipped: [String] (why)}
       def self.apply_tools(registry, bundle, specs, context)
         wanted = specs.to_h { |spec| [spec[:name], spec] }
         changed = false
         registry.entries.each do |entry|
           next unless entry.source == bundle
-          next if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
+
+          if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
+            entry_fields(spec, context).slice(:handler, :preview, :targets, :refs).each { |key, value| entry[key] = value }
+            next
+          end
 
           registry.unregister(entry.name)
           changed = true
@@ -295,23 +306,30 @@ module Samagotchi
       end
 
       # Registry#register's keywords for a tool declaration: its block
-      # wrapped as a handler (typed args, the Context), preview, targets.
+      # wrapped as a handler (typed args, the Context), preview, targets, refs.
       def self.entry_fields(spec, context)
         block = spec[:block]
-        preview = spec[:preview]
-        targets = spec[:targets]
         parameters = spec[:schema][:parameters]
+        preview = per_call(spec[:preview], parameters)
         {
           schema: spec[:schema], label: spec[:label],
           handler: lambda { |call, _kctx|
             result = block.call(Api.args_of(call, parameters), context)
             Api.result_text(result)
           },
-          preview: preview && ->(call) { preview.call(Api.args_of(call, parameters))&.to_s },
-          targets: targets && ->(call) { targets.call(Api.args_of(call, parameters)) }
+          preview: preview && ->(call) { preview.call(call)&.to_s },
+          targets: per_call(spec[:targets], parameters),
+          refs: per_call(spec[:refs], parameters)
         }
       end
 
+      # A plugin's args → value lambda (+fn+) as call → value: it gets the
+      # call's typed args (Api.args_of), as the tool's block does. nil
+      # without one.
+      def self.per_call(fn, parameters)
+        fn && ->(call) { fn.call(Api.args_of(call, parameters)) }
+      end
+
       # A tool's result as the model reads it: a String (a ToolResult too,
       # with its images) as it is, a Hash or Array as JSON (its #to_s is
       # Hash#inspect, which changes with the Ruby version), else #to_s.

data/lib/samagotchi/reasoning_history.rb

@@ -7,9 +7,9 @@ module Samagotchi
   # Which of its own reasoning a chat host's model gets back
   # (LLM::ChatLoop sends it as reasoning_content on its earlier replies):
   #
-  #   turn  the running turn's replies only (the tool-call rounds since the
-  #         last user message); what Qwen's, Gemma 4's and DeepSeek's
-  #         templates and the hosted APIs expect
+  #   turn  the running turn's replies only (since the turn's start; a
+  #         steer, a plugin's nudge or a Continue's text merged into the
+  #         turn doesn't reset it, as on a native host: .run_start)
   #   drop  none
   #   all   every reply that has reasoning, earlier turns too (a direct
   #         DeepSeek API with tools wants this)
@@ -17,7 +17,8 @@ module Samagotchi
   # Order (#resolve): the session's own level (/reasoning-history), then
   # SAMAGOTCHI_REASONING_HISTORY, models.<key>.reasoning_history,
   # hosts.<name>.reasoning_history, then turn. Native hosts ignore it:
-  # KernelLoop keeps the running turn's reasoning on its own.
+  # KernelLoop keeps the running turn's reasoning on its own, from the
+  # run's start (.run_start).
   module ReasoningHistory
     LEVELS = %i[drop turn all].freeze
     DEFAULT = :turn
@@ -118,6 +119,23 @@ module Samagotchi
       end
     end
 
+    # Where a run's own reasoning starts in +messages+: its start (+since+;
+    # nil without one). Inside one run nothing re-sanitizes, so an entry the
+    # run merged (a steer, a delegate report, the Qwen recovery prompt) left
+    # the reasoning before it in the prompt: it stays. Only a user or
+    # turn_start entry added after the run ended (after its last model
+    # message: a !cmd's output) starts it again past itself.
+    # @param messages [Array<Hash>] the conversation
+    # @param since [Integer, nil] the run's start
+    # @return [Integer, nil]
+    def run_start(messages, since)
+      return nil if since.nil?
+
+      last_reply = messages.rindex { |m| m[:role].to_s == "model" } || -1
+      query = messages.rindex { |m| m[:role].to_s == "user" || m[:turn_start] == true }
+      query && query > last_reply ? [query + 1, since].max : since
+    end
+
     # "drop (models: qwen)", "turn (default)".
     def label(level, source) = "#{level} (#{source || "default"})"
 

data/lib/samagotchi/row_refs.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "log"
+require_relative "ref"
+
+module Samagotchi
+  # The refs a plugin tool gives its row (chi.tool's refs: lambda, traceable
+  # refs P5d): what the call traces to (a ticket, a PR, a file), each a Ref
+  # whose +to_h+ the row carries as +refs+ on tool_call_started and
+  # tool_call_completed (ToolRowFields::EVENT_KEYS), saved with the result
+  # as tool_refs (ToolResponse::SAVED_KEYS) for a reload, which has no
+  # plugins (Web::MessageParts). Display only: the model never sees them.
+  #
+  # A file ref is any file under the session's folder (plan D7): a relative
+  # path is resolved against it, a path outside it is dropped. The folder
+  # counts under its own spelling and its real path (macOS /tmp is
+  # /private/tmp), and a kept path is stored under the real one, so a
+  # reload under either spelling keeps it. The page
+  # shows the first ref on the row's title and the rest in its menu.
+  module RowRefs
+    # Per row, so a plugin can't bloat the events or session.json.
+    MAX_REFS = 20
+    # The row's refs' JSON; a ref that would cross it is left out.
+    MAX_BYTES = 64 * 1024
+
+    module_function
+
+    # Runs +fn+ (the tool's refs: lambda, as Api.per_call wraps it: call →
+    # a list of {kind:, target:, label:, actions:}) on +call+. Never
+    # raises: a lambda that raises or returns something other than a list
+    # gives none, and a bad ref is dropped; both are logged (warn, not
+    # echoed: the turn's live region is on screen).
+    # @param cwd [String, nil] the session's folder
+    # @return [Array<Hash>] Ref#to_h each, deduped, at most MAX_REFS
+    def for(fn, call, cwd:)
+      return [] unless fn
+
+      tool = call[:name].to_s
+      raw = fn.call(call)
+      return [] if raw.nil?
+      raise ArgumentError, "refs: returned #{raw.class}, not a list" unless raw.is_a?(Array)
+
+      build(raw, cwd) { |why| Log.warn(:plugins, "tool_refs_rejected", tool: tool, reason: why) }
+    rescue StandardError => e
+      Log.warn(:plugins, "tool_refs_failed", tool: tool, error: "#{e.class}: #{e.message}")
+      []
+    end
+
+    # Stored refs (+raw+, a saved tool_refs entry), each rebuilt and
+    # checked again as #for checks a lambda's: a stored file is never
+    # trusted. What isn't valid any more is dropped, a relative path too
+    # (it was stored absolute). Never raises: a reload must show the
+    # conversation.
+    # @return [Array<Hash>]
+    def for_display(raw, cwd:)
+      return [] unless raw.is_a?(Array)
+
+      build(raw, cwd, relative: false) { |_why| nil }
+    rescue StandardError
+      []
+    end
+
+    # +raw+'s valid refs as Ref#to_h; +rejected+ gets why each other one
+    # was dropped. +relative+: a relative file path is resolved against
+    # +cwd+ (else dropped).
+    def build(raw, cwd, relative: true, &)
+      roots = roots(cwd)
+      bytes = 2 # the list's []
+      raw.each_with_object([]) do |value, refs|
+        break refs if refs.length >= MAX_REFS
+
+        hash = inside(Ref.from(value), roots, relative).to_h
+        next if refs.include?(hash)
+
+        size = JSON.generate(hash).bytesize + (refs.empty? ? 0 : 1)
+        break refs if bytes + size > MAX_BYTES
+
+        bytes += size
+        refs << hash
+      # One junk ref ({1 => "x"}, a nil target) goes alone.
+      rescue ArgumentError, TypeError, NoMethodError => e
+        yield(e.message)
+      end
+    end
+    private_class_method :build
+
+    # +cwd+ as [its spelling, its real path] (one when they are the same,
+    # none without a +cwd+). absolute_path, not expand_path: a leading ~ is
+    # a name, never a home. One realpath per row: the lambda's refs are
+    # checked together.
+    def roots(cwd)
+      return [] if cwd.to_s.empty?
+
+      given = File.absolute_path(cwd.to_s)
+      real = begin
+        File.realpath(given)
+      rescue SystemCallError
+        given
+      end
+      [given, real].uniq
+    end
+    private_class_method :roots
+
+    # +ref+ with a file's path absolute, resolved against the folder
+    # (+roots+, #roots), under its real spelling.
+    # @raise [ArgumentError] a relative path with no folder (or not
+    #   +relative+), or a path outside the folder
+    def inside(ref, roots, relative)
+      return ref unless ref.kind == Ref::FILE
+
+      path = ref.target[:path]
+      unless File.absolute_path?(path) || (relative && roots.any?)
+        raise ArgumentError, "a file ref's relative path needs the session folder"
+      end
+      return ref if roots.empty?
+
+      path = File.absolute_path(path, roots.first)
+      root = roots.find { |dir| path == dir || path.start_with?(dir.end_with?("/") ? dir : "#{dir}/") }
+      raise ArgumentError, "a file ref outside the session folder (#{path})" unless root
+
+      ref.with(target: ref.target.merge(path: "#{roots.last}#{path.delete_prefix(root)}").freeze)
+    end
+    private_class_method :inside
+  end
+end

data/lib/samagotchi/session_metrics.rb

@@ -416,10 +416,20 @@ module Samagotchi
     # analytics.json in the session directory. Atomic write; failures are
     # swallowed (analytics must never break the running session).
     # @param state_dir [String, nil]
+    # @param running_turn [Boolean] also save the running turn's record so
+    #   far (a worker's turn checkpoint): as the turn a worker killed now
+    #   would leave, canceled with reason worker_stopped (TurnNote's), up to
+    #   its completed_at. The next collector loads it with the others; the
+    #   turn's own end writes over it. Only the file has it.
     # @return [Boolean] true on success
-    def persist(state_dir: nil)
+    def persist(state_dir: nil, running_turn: false)
       sid, data, turn_count = @mutex.synchronize do
-        [@session_id, build_snapshot(:all).merge(active_turn: nil, active_tools: []), @turn_records.size]
+        data = build_snapshot(:all).merge(active_turn: nil, active_tools: [])
+        if running_turn && @turn
+          data[:turn_records] << running_turn_record
+          data[:cancellations] += 1
+        end
+        [@session_id, data, @turn_records.size]
       end
       return false if sid.nil? || sid.to_s.empty?
 
@@ -611,6 +621,18 @@ module Samagotchi
       end
     end
 
+    # The running turn's record so far, as end_turn would make it for a
+    # turn a worker died in (#persist's running_turn). Its open generation
+    # (none at an iteration boundary) and running tool calls are left out.
+    # Caller holds the mutex.
+    def running_turn_record
+      {
+        id: @turn.id, status: "canceled", started_at: @turn.started_at, completed_at: now.iso8601(3),
+        duration_ms: elapsed_ms(@turn.started_monotonic), cancellation_reason: "worker_stopped",
+        continue: @turn.continue, resumed: @turn.resumed
+      }.merge(turn_token_fields(@turn))
+    end
+
     # What turn_failed's line is made of (format.js failedTurnText): a
     # provider error's summary, else the message (capped: a server's error
     # page can be long) and class, and the steps that stayed (kept_steps).

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -363,7 +363,7 @@ module Samagotchi
 
       # A cancel's reason as the UIs name it (anything else as it is);
       # spec/shared/labels_matrix.json pins it for both.
-      CANCEL_REASONS = { "ctrl_c" => "Ctrl-C", "user" => "stopped", "hook" => "by a hook" }.freeze
+      CANCEL_REASONS = { "ctrl_c" => "Ctrl-C", "user" => "stopped", "hook" => "by a hook", "worker_stopped" => "worker stopped" }.freeze
       # A canceled turn's mark: a stop someone chose (Ctrl-C, Stop, a hook),
       # not an error's ✕ (timing.js STOP_MARK; the labels matrix pins it).
       STOP_MARK = "■"

data/lib/samagotchi/terminal_ui.rb

@@ -885,12 +885,35 @@ module Samagotchi
       end
 
       # The REPL keeps the kernel's conversation as-is (no [No response]
-      # placeholder), so /continue resumes from the tool results.
-      session.messages = result.conversation
+      # placeholder), so /continue resumes from the tool results; the
+      # answer keeps what the after_turn hooks stored on it.
+      session.messages = with_answer_display(result.conversation, session.messages)
       @turn_flow.after_turn(result, continue: continue)
       save_session(session)
     end
 
+    # The answer's display keys (Engine#store_answer_display put them on the
+    # session's last message) carried onto +conversation+'s last message,
+    # when that is the same answer; +conversation+ as it is otherwise.
+    ANSWER_DISPLAY_KEYS = [AnswerDisplay::KEY, AnswerRefs::KEY].freeze
+    private_constant :ANSWER_DISPLAY_KEYS
+
+    def with_answer_display(conversation, stored)
+      answer = Array(conversation).last
+      kept = Array(stored).last
+      return conversation unless answer.is_a?(Hash) && kept.is_a?(Hash) && message_field(answer, :role).to_s == "model"
+      return conversation unless message_field(kept, :role).to_s == "model" &&
+                                 message_field(kept, :content) == message_field(answer, :content)
+
+      extra = ANSWER_DISPLAY_KEYS.each_with_object({}) do |key, found|
+        value = message_field(kept, key)
+        found[key] = value unless value.nil?
+      end
+      extra.empty? ? conversation : conversation[0...-1] + [answer.merge(extra)]
+    end
+
+    def message_field(message, key) = message.key?(key) ? message[key] : message[key.to_s]
+
     def save_session(session)
       @engine.store_model!(session)
       session.save
@@ -970,7 +993,7 @@ module Samagotchi
       end
       canceled = result&.canceled?
       if result && !canceled
-        session.messages = result.conversation if result.conversation.is_a?(Array)
+        session.messages = with_answer_display(result.conversation, session.messages) if result.conversation.is_a?(Array)
         @engine.store_model!(session)
         session.save
       end

data/lib/samagotchi/tool_activity.rb

@@ -211,12 +211,16 @@ module Samagotchi
     # "stopped" for a
     # task_wait the user's Stop ended (the task itself runs on), for one
     # whose task was stopped (the stop-task button, or the model's task_stop),
-    # and for a command the user's Stop killed or kept from starting: a
-    # cancel, not a failure (its text still starts "Error:" for the model).
+    # and for a command the user's Stop (or a signal to chi) killed or kept
+    # from starting: a cancel, not a failure (its text still starts "Error:"
+    # for the model).
     def tool_activity_status(result, tool_name = nil, command: nil)
       text = result.to_s
-      return "stopped" if text == Tools::Execute::NOT_RUN_ON_STOP
-      return "stopped" if tool_name == Tools::Execute::NAME && text.start_with?(Tools::Execute::STOPPED_BY_USER)
+      return "stopped" if [Tools::Execute::NOT_RUN_ON_STOP, Tools::Execute::NOT_RUN_ON_SIGNAL].include?(text)
+      if tool_name == Tools::Execute::NAME &&
+         text.start_with?(Tools::Execute::STOPPED_BY_USER, Tools::Execute::STOPPED_BY_SIGNAL)
+        return "stopped"
+      end
       return "error" if text.start_with?("Error:")
       # Still running, as a task: its output tail may hold any "exit: N".
       return "ok" if handed_over?(tool_name, text)

data/lib/samagotchi/tool_response.rb

@@ -9,11 +9,11 @@ module Samagotchi
   # (max_tool_output_chars).
   module ToolResponse
     SEPARATOR = "\n\n---\n\n"
-    # Saved with a result for the web's reload (a plugin tool's params line
-    # and label, an edit/write's diff) and for the LLMContextView (each
+    # Saved with a result for the web's reload (a plugin tool's params line,
+    # label and row refs, an edit/write's diff) and for the LLMContextView (each
     # run's chi-owned id, ToolIds, and a strategy's edits by id,
     # LLMContextEdit); the prompt never renders them.
-    SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_ids edits].freeze
+    SAVED_KEYS = %i[tool_params tool_labels tool_diffs tool_refs tool_ids edits].freeze
     # A run's "[name]" lead: the name, then a newline, a space or the end.
     LEAD = /\A\[([^\]\s]+)\](?:\n| |\z)/
 
@@ -60,7 +60,7 @@ module Samagotchi
         entry[:image_counts] = runs.map { |run| Array(run[:images]).size }
       end
       saved = { tool_params: runs.map { |run| run[:shown_params] }, tool_labels: runs.map { |run| run[:shown_label] },
-                tool_diffs: runs.map { |run| run[:diff] } }
+                tool_diffs: runs.map { |run| run[:diff] }, tool_refs: runs.map { |run| run[:refs] } }
       saved.each { |key, values| entry[key] = values if values.any? }
       entry[:tool_ids] = ids
       entry
@@ -75,6 +75,7 @@ module Samagotchi
       entry[:tool_params] = run[:shown_params] if run[:shown_params]
       entry[:tool_labels] = run[:shown_label] if run[:shown_label]
       entry[:tool_diffs] = run[:diff] if run[:diff]
+      entry[:tool_refs] = run[:refs] if run[:refs]
       entry[:tool_ids] = ids
       entry
     end

data/lib/samagotchi/tool_row_fields.rb

@@ -16,13 +16,15 @@ module Samagotchi
   #   tool_call_completed (ToolActivity.tool_activity_event builds that
   #   activity itself, for the TUI and the metrics);
   # * EVENT_KEYS: top-level on both, so a UI that missed the start (a
-  #   replay gap) builds its row from the completed event.
+  #   replay gap) builds its row from the completed event. +refs+ (a
+  #   plugin tool's, RowRefs) is one, but ToolRunner adds it: #for has no
+  #   plugins, so a reload reads the saved tool_refs instead.
   #
   # params and label stay where they are: their sources differ per path
   # (the registry's preview, a plugin's label, the saved shown params).
   module ToolRowFields
     ACTIVITY_KEYS = %i[title called_as].freeze
-    EVENT_KEYS = %i[view ref].freeze
+    EVENT_KEYS = %i[view ref refs].freeze
     KEYS = (ACTIVITY_KEYS + EVENT_KEYS).freeze
 
     module_function

data/lib/samagotchi/tool_runner.rb

@@ -2,6 +2,7 @@
 
 require_relative "tool_activity"
 require_relative "tool_row_fields"
+require_relative "row_refs"
 require_relative "guardrails"
 require_relative "vision_context"
 require_relative "log"
@@ -41,7 +42,8 @@ module Samagotchi
     #   shown_params: the params line the live row showed, and shown_label:
     #   its label ("chrome: screenshot"), only for a tool that isn't built in
     #   (the loops save them with the result, so a reload without the plugin
-    #   shows the same row), and diff: what an edit/write changed in its
+    #   shows the same row), refs: its row's refs (a plugin tool's refs:,
+    #   RowRefs; saved likewise), and diff: what an edit/write changed in its
     #   file (EditPreview.change; also on tool_call_completed, never in the
     #   model's output)
     def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
@@ -55,9 +57,12 @@ module Samagotchi
       started = { type: :tool_call_started, iteration: iteration, call_count: call_count, call_index: call_index,
                   tool: call[:name], call: call.dup, params: params }
       started[:label] = label if label
-      # Its row fields (ToolRowFields: title, called_as, view, ref); the worker runs in
-      # its session's working directory.
+      # Its row fields (ToolRowFields: title, called_as, view, ref, and a
+      # plugin tool's refs); the worker runs in its session's working
+      # directory.
       fields = ToolRowFields.for(call[:name], call, cwd: Dir.pwd)
+      refs = RowRefs.for(tools && !call[:name].nil? ? tools[call[:name]]&.refs : nil, call, cwd: session_cwd)
+      fields[:refs] = refs unless refs.empty?
       started.merge!(fields)
       emit(on_stream_event, started)
 
@@ -121,6 +126,7 @@ module Samagotchi
       run[:images] = images if images&.any?
       run[:shown_params] = params if params && plugin_tool?(call[:name])
       run[:shown_label] = label if label
+      run[:refs] = refs unless refs.empty?
       run[:diff] = diff if diff
       run
     end
@@ -249,6 +255,13 @@ module Samagotchi
       [result[:output], *notes].join("\n")
     end
 
+    # The session's folder (the Engine's, KernelLoop#session_cwd), else the
+    # process's: a bare kernel (specs) has none.
+    def session_cwd
+      cwd = @kernel.respond_to?(:session_cwd) && @kernel.session_cwd&.call
+      cwd.to_s.empty? ? Dir.pwd : cwd
+    end
+
     # The kernel's tools, for the activity line of a tool that isn't built in.
     def tools = @kernel.tools
 

data/lib/samagotchi/tools/builtins.rb

@@ -77,7 +77,7 @@ module Samagotchi
                     start_line: call[:start_line], end_line: call[:end_line])
         end,
         TaskCreate::NAME => lambda do |call, kctx|
-          next Execute::NOT_RUN_ON_STOP if cancelled_proc(kctx).call
+          next Execute.not_run(stop_reason_proc(kctx)) if cancelled_proc(kctx).call
 
           TaskCreate.call(call[:content], cwd: call[:cwd], env: call[:env],
                           marker_env: task_marker_env(kctx, call[:env]))
@@ -87,7 +87,8 @@ module Samagotchi
                                         done_pattern: call[:done_pattern], cancelled: cancelled_proc(kctx))
         end,
         Execute::NAME => lambda do |call, kctx|
-          Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx), env: parent_env(kctx))
+          Execute.call(call[:content], cwd: call[:cwd], cancelled: cancelled_proc(kctx), stop_reason: stop_reason_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],
@@ -163,6 +164,12 @@ module Samagotchi
         -> { !!peers&.cancelled? }
       end
 
+      # The running turn's stop reason (:signal, :manual, …), nil without one.
+      def stop_reason_proc(kctx)
+        peers = kctx.peers
+        -> { peers.respond_to?(:cancel_reason) ? peers.cancel_reason : nil }
+      end
+
       # @param command_description [Boolean] false: execute declares no
       #   description parameter (execute.description off)
       # @param policy [String, nil] llm_context.policy, the sentence

data/lib/samagotchi/tools/execute.rb

@@ -27,6 +27,10 @@ module Samagotchi
       NOT_RUN_ON_STOP = "Error: not run, the user stopped the turn"
       # The first words of a command the user's Stop killed.
       STOPPED_BY_USER = "Error: command stopped by the user"
+      # The same two when a signal to chi (a worker's TERM, HUP or INT)
+      # stopped the turn: its cancel reason is :signal.
+      NOT_RUN_ON_SIGNAL = "Error: not run, a signal to chi stopped the turn"
+      STOPPED_BY_SIGNAL = "Error: command stopped by a signal to chi"
       # The first words of a command killed at the limit in kill mode (hooks
       # match on it).
       TIMEOUT_PREFIX = "Error: command timed out after"
@@ -73,11 +77,13 @@ module Samagotchi
 
       # @param cancelled [#call] true once the user stopped the turn: the
       #   command is killed (or not started) and its output so far returned
+      # @param stop_reason [#call] the stop's reason (:signal: a signal to
+      #   chi, which the result then names instead of the user)
       # @param env [Hash, nil] added to the command's environment
       # @param on_timeout [Symbol, String, nil] :task or :kill (ON_TIMEOUT);
       #   nil reads execute.on_timeout
-      def self.call(command, cwd: nil, cancelled: -> { false }, env: nil, on_timeout: nil)
-        return NOT_RUN_ON_STOP if cancelled.call
+      def self.call(command, cwd: nil, cancelled: -> { false }, stop_reason: -> {}, env: nil, on_timeout: nil)
+        return not_run(stop_reason) if cancelled.call
 
         command = command.strip
         resolved_cwd = resolve_cwd(cwd)
@@ -109,11 +115,17 @@ module Samagotchi
         # a long command, and return whatever it printed before it was killed.
         stopped_result("#{TIMEOUT_PREFIX} #{timeout_sec}s\n#{TIMEOUT_HINT}", e)
       rescue CommandCancelled => e
-        stopped_result("#{STOPPED_BY_USER} after #{e.elapsed.round}s (killed; rerun it if still needed)", e)
+        first = signal?(stop_reason) ? STOPPED_BY_SIGNAL : STOPPED_BY_USER
+        stopped_result("#{first} after #{e.elapsed.round}s (killed; rerun it if still needed)", e)
       rescue StandardError => e
         "Error: #{e.message}"
       end
 
+      # What a command the turn's stop kept from starting returns.
+      def self.not_run(stop_reason) = signal?(stop_reason) ? NOT_RUN_ON_SIGNAL : NOT_RUN_ON_STOP
+
+      def self.signal?(stop_reason) = stop_reason.call == :signal
+
       # execute.on_timeout, or the caller's: :task (the default) or :kill.
       def self.on_timeout_mode(value)
         value = Samagotchi::Config.get("execute.on_timeout") if value.nil? || value.to_s.strip.empty?

data/lib/samagotchi/tools/peers.rb

@@ -10,11 +10,12 @@ module Samagotchi
     # can't host one), and the model the session runs on (model_ref: the
     # resolved ref, live after /model), and the session's own thinking level
     # (thinking: nil without one) and reasoning_history level
-    # (reasoning_history: nil without one). Engine hands KernelLoop one that follows its current
+    # (reasoning_history: nil without one), and why the turn was canceled
+    # (cancel_reason: :signal, :manual, …; nil while it runs). Engine hands KernelLoop one that follows its current
     # session (Engine::PeerView); this plain one is for specs and a kernel
     # without an Engine.
     Peers = Struct.new(:session_id, :cwd, :state_dir, :cancelled, :relay, :model_ref, :thinking, :reasoning_history,
-                       keyword_init: true) do
+                       :cancel_reason, keyword_init: true) do
       # @return [Boolean] the turn was canceled (:cancelled is a proc or a value)
       def cancelled?
         cancelled.respond_to?(:call) ? !!cancelled.call : !!cancelled

data/lib/samagotchi/tools/registry.rb

@@ -20,11 +20,13 @@ module Samagotchi
       #   tool" when nil); ToolActivity knows the built-ins' own
       # @!attribute preview [#call, nil] call → the activity line's params
       # @!attribute targets [#call, nil] call → what guardrail rules match
+      # @!attribute refs [#call, nil] call → the row's refs (a plugin's
+      #   refs:, RowRefs checks what it gives)
       # @!attribute source [String] "core", or the bundle that added it
       # @!attribute layer [Symbol, nil] the LLM context layer the tool
       #   belongs to (LLMContextStrategy): offered only in a turn running
       #   under it (forget_outputs, :forget); nil: always
-      Entry = Struct.new(:name, :schema, :handler, :label, :preview, :targets, :source, :layer, keyword_init: true) do
+      Entry = Struct.new(:name, :schema, :handler, :label, :preview, :targets, :refs, :source, :layer, keyword_init: true) do
         def core? = source == "core"
 
         # Offered in a turn under +layers+ (the turn's LLM context layers).
@@ -36,11 +38,11 @@ module Samagotchi
       end
 
       # @return [Entry]
-      def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, source: "core", layer: nil)
+      def register(name, schema:, handler:, label: nil, preview: nil, targets: nil, refs: nil, source: "core", layer: nil)
         raise ArgumentError, "tool #{name} is already registered" if @entries.key?(name)
 
         @entries[name] = Entry.new(name: name, schema: schema, handler: handler, label: label, preview: preview,
-                                   targets: targets, source: source, layer: layer)
+                                   targets: targets, refs: refs, source: source, layer: layer)
       end
 
       # Remove a tool (a plugin's tool set changed after load).

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.61.0"
+  VERSION = "0.62.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end